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 SDK

Stringee Android SDK is distributed as an AAR and can be added to your project by referencing the AAR remotely with Maven.

1. Navigate to your build.gradle at the project level and include the following:

   buildscript {
       repositories {
           ...
           mavenCentral()
       }
   }
   ...
   allprojects {
       repositories {
           ...
           mavenCentral()
       }
   }

2. Navigate to your build.gradle at the app level and include the following:

   android {
       ...
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
   }
   dependencies {    
       ...
       implementation 'com.stringee.sdk.android:stringee-android-sdk:1.8.0'
       implementation 'com.android.volley:volley:1.2.0'
   }

3. Sync your project

Permissions and proguard

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.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

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

-dontwarn org.apache.**
-keep class com.stringee.** { *; }
-keep class org.apache.** { *; }

Customer

Step 1: Initialize the StringeeClient

import com.stringee.StringeeClient;
...
private StringeeClient stringeeClient;
...
stringeeClient = new StringeeClient(this);

The StringeeClient class is defined in Stringee SDK. It includes methods interacting with Stringee Server.

Step 2: Get chat profile

Chat Profile is an object which will let you know:

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

stringeeClient.getChatProfile("YOUR_WIDGET_KEY", new CallbackListener<ChatProfile>() {
    @Override
    public void onSuccess(ChatProfile profile) {
    }

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

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:

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

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

In which:

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

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 a StringeeConnectionListener interface with StringeeClient object before connecting.

2. client.setConnectionListener(new StringeeConnectionListener() {
       @Override
       public void onConnectionConnected(StringeeClient stringeeClient, boolean isReconnecting) {
       }
   
       @Override
       public void onConnectionDisconnected(StringeeClient stringeeClient, boolean isReconnecting) {
       }
   
       @Override
       public void onIncomingCall(StringeeCall stringeeCall) {
       }
   
       @Override
       public void onIncomingCall2(StringeeCall2 stringeeCall2) {
       }
   
       @Override
       public void onConnectionError(StringeeClient stringeeClient, StringeeError stringeeError) {
       }
   
       @Override
       public void onRequestNewToken(StringeeClient stringeeClient) {
       }
   
       @Override
       public void onCustomMessage(String from, JSONObject msg) {
       }
   
       @Override
       public void onTopicMessage(String from, JSONObject msg) {
       }
   });        

• When the client connects to Stringee Server, the onConnectionConnected(StringeeClient stringeeClient, boolean isReconnecting) method is called.
• When the client disconnects to Stringee Server, the onConnectionDisconnected(StringeeClient stringeeClient, boolean isReconnecting) method is called
• When the client fails to connect to Stringee Server, the onConnectionError(StringeeClient stringeeClient, StringeeError stringeeError) method is called.
• When the token is expired, the onRequestNewToken(StringeeClient stringeeClient) is called. You will need re-generate a new token and connect again.

2. To listen for object (Conversation, Message) change events, you will need register a ChangeEventListenter interface:

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

3. To listen for live chat events, you will need register a LiveChatEventListener interface:

   stringeeClient.setLiveChatEventListener(new LiveChatEventListener() {
       @Override
       public void onReceiveChatRequest(ChatRequest chatRequest) {
       // Invoked when receive chat request
       }
   
       @Override
       public void onReceiveTransferChatRequest(ChatRequest chatRequest) {
       // Invoked when receive transfer chat request from other agent
       }
   
       @Override
       public void onTimeoutAnswerChat(ChatRequest chatRequest) {
       // Invoked when time out chat request for agent
       }
   
       @Override
       public void onTimeoutInQueue(Conversation conversation) {
       // Invoked when no agent answer this chat and time out route in queue
       }
   
       @Override
       public void onConversationEnded(Conversation conversation, User endedByUser) {
       // Invoked when conversation ended
       }
   });

4. Connect by calling:

   stringeeClient.connect(accessToken);

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:

stringeeClient.updateUser("USER_NAME", "USER_EMAIL", "USER_AVATAR", new StatusListener() {
    @Override
    public void onSuccess() {
    }

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

Then start a live chat conversation by calling:

stringeeClient.createLiveChat(queueId, new CallbackListener<Conversation>() {
    @Override
    public void onSuccess(Conversation conversation) {
    }

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

In which:

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

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(stringeeClient, new StatusListener() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(StringeeError error) {

    }
});

In which:

• stringeeClient: The StringeeClient instance.

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 a StringeeConnectionListener interface with StringeeClient object before connecting.

   client.setConnectionListener(new StringeeConnectionListener() {
       @Override
       public void onConnectionConnected(StringeeClient stringeeClient, boolean isReconnecting) {
       }
   
       @Override
       public void onConnectionDisconnected(StringeeClient stringeeClient, boolean isReconnecting) {
       }
   
       @Override
       public void onIncomingCall(StringeeCall stringeeCall) {
       }
   
       @Override
       public void onIncomingCall2(StringeeCall2 stringeeCall2) {
       }
   
       @Override
       public void onConnectionError(StringeeClient stringeeClient, StringeeError stringeeError) {
       }
   
       @Override
       public void onRequestNewToken(StringeeClient stringeeClient) {
       }
   
       @Override
       public void onCustomMessage(String from, JSONObject msg) {
       }
   
       @Override
       public void onTopicMessage(String from, JSONObject msg) {
       }
   });        

• When the client connects to Stringee Server, the onConnectionConnected(StringeeClient stringeeClient, boolean isReconnecting) method is called.
• When the client disconnects to Stringee Server, the onConnectionDisconnected(StringeeClient stringeeClient, boolean isReconnecting) method is called
• When the client fails to connect to Stringee Server, the onConnectionError(StringeeClient stringeeClient, StringeeError stringeeError) method is called.
• When the token is expired, the onRequestNewToken(StringeeClient stringeeClient) is called. You will need re-generate a new token and connect again.

2. To listen for object (Conversation, Message) change events, you will need register a ChangeEventListenter interface:

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

3. To listen for live chat events, you will need register a LiveChatEventListener interface:

   stringeeClient.setLiveChatEventListener(new LiveChatEventListener() {
       @Override
       public void onReceiveChatRequest(ChatRequest chatRequest) {
       // Invoked when receive chat request
       }
   
       @Override
       public void onReceiveTransferChatRequest(ChatRequest chatRequest) {
       // Invoked when receive transfer chat request from other agent
       }
   
       @Override
       public void onTimeoutAnswerChat(ChatRequest chatRequest) {
       // Invoked when time out chat request for agent
       }
   
       @Override
       public void onTimeoutInQueue(Conversation conversation) {
       // Invoked when no agent answer this chat and time out route in queue
       }
   
       @Override
       public void onConversationEnded(Conversation conversation, User endedByUser) {
       // Invoked when conversation ended
       }
   });

4. Connect by calling:

   stringeeClient.connect(accessToken);

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(stringeeClient, new CallbackListener<Conversation>() {
    @Override
    public void onSuccess(Conversation conversation) {
    }

    @Override
    public void onError(StringeeError errorInfo) {
        super.onError(errorInfo);
    }
});

In which:

• stringeeClient: The StringeeClient instance.

Reject

For reject chat request, call the following function:

chatRequest.reject(stringeeClient, new StatusListener() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onError(StringeeError errorInfo) {
        super.onError(errorInfo);
    }
});

In which:

• stringeeClient: The StringeeClient instance.

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(stringeeClient, new StatusListener() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(StringeeError error) {

    }
});

In which:

• stringeeClient: The StringeeClient instance.

Extra

Create a ticket for a miss chat

To create a ticket for a missed live chat conversation, you call:

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

    }

    @Override
    public void onError(StringeeError error) {

    }
});

Chat Transcript

If you wanna send chat's content to an email at any time, you call:

conversation.sendChatTranscriptTo(stringeeClient, "EMAIL", "DOMAIN", new StatusListener() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(StringeeError error) {

    }
});