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:

Login to your StringeeX account as an admin
In the Setting -> Chat Management -> Chat Widget -> Embed web widget, get the key in the URL

Install stringee-react-native package

In your terminal (Command Prompt in Windows), change into your React Native project's directory
In your terminal (Command Prompt in Windows), run $ npm install [email protected]

React Native 0.60 or later and JDK 17 are required. Autolinking configures the native module automatically. Expo projects must use a development or production build; Expo Go is not supported.

Setup

Android

Use an AndroidX-enabled project with minSdkVersion 21 or later.

Permissions

The Stringee Android SDK requires some permissions from your AndroidManifest

Open up android/app/src/main/AndroidManifest.xml
Add the following lines:

<!--Internet-->
<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" />

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

The package already declares Stringee Android SDK 2.1.13 and WebRTC 144.7559.09; do not add those native dependencies again in the app.

iOS

Stringee React Native SDK requires iOS 13.0 or later.

In your terminal, change into the iOS directory and run the following command:
```
pod install --repo-update
```
After running CocoaPods, open the generated .xcworkspace file.

Add camera and microphone usage descriptions to Info.plist if your app also uses call features:

<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) uses Camera</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) uses Microphone</string>

Customer

Step 1: Connect to Stringee Server

Initialize StringeeClient

import {StringeeClient, StringeeClientListener, UserInfo} from 'stringee-react-native-v2';
...
const stringeeClient = new StringeeClient();
let queueId = null;
let conversation = null;
let isClientConnected = false;

// Listen for the StringeeClient event
const stringeeClientListener = new StringeeClientListener();
// Invoked when the StringeeClient is connected
stringeeClientListener.onConnect = (stringeeClient, userId) => {
   isClientConnected = true;
   console.log('onConnect: ', userId);
};
// Invoked when the StringeeClient is disconnected
stringeeClientListener.onDisConnect = (stringeeClient) => {
   console.log('onDisConnect');
};
// Invoked when the StringeeClient connection fails
stringeeClientListener.onFailWithError = (stringeeClient, code, message) => {
   console.log('onFailWithError: ', message);
};
// Invoked when your token is expired
stringeeClientListener.onRequestAccessToken = (stringeeClient) => {
   console.log('onRequestAccessToken');
};
// Invoked when conversation or message update
stringeeClientListener.onObjectChange = (stringeeClient, objectType, objectChanges, changeType) => {
   console.log('onObjectChange: ', objectType, objectChanges, changeType);
};
// Invoked when a chat request timed out and no agent in queue accept
stringeeClientListener.onTimeoutInQueue = (stringeeClient, convId, customerId, customerName) => {
   console.log('onTimeoutInQueue: ', convId, customerId, customerName);
};
// Invoked when the conversation is ended
stringeeClientListener.onConversationEnded = (stringeeClient, convId, endedby) => {
   console.log('onConversationEnded: ', convId, endedby);
};
stringeeClient.setListener(stringeeClientListener);

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').then(chatProfile => {
    console.log('getChatProfile', JSON.stringify(chatProfile));
    if (chatProfile.queues && chatProfile.queues.length > 0) {
        queueId = chatProfile.queues[0].id;
    }
}).catch(console.log);

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. Call getLiveChatToken(...) on the StringeeClient object:

stringeeClient.getLiveChatToken('YOUR_WIDGET_KEY', 'YOUR_CUSTOMER_NAME', 'YOUR_CUSTOMER_EMAIL').then(token => {
    console.log('getLiveChatToken', token);
    // After get token then can connect
    stringeeClient.connect(token);
}).catch(console.log);

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: 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 StringeeClient object:

if (!isClientConnected || !queueId) {
    return;
}
const userInfo = new UserInfo();
userInfo.name = 'USER_NAME';
userInfo.email = 'USER_EMAIL';
userInfo.avatar = 'USER_AVATAR';
stringeeClient.updateUserInfo(userInfo).then(() => {
    console.log('updateUserInfo success');
}).catch(console.log);

Then call createLiveChatConversation(...) on the StringeeClient object:

stringeeClient.createLiveChatConversation(queueId).then(createdConversation => {
    conversation = createdConversation;
    console.log('createLiveChatConversation', JSON.stringify(conversation));
}).catch(console.log);

In which:

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

Step 5: Messages

Follow this instruction Messages

Step 6: End a live chat conversation

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

if (!conversation) {
    return;
}
conversation.endChat().then(() => {
    console.log('endChat success');
}).catch(console.log);

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.

Initialize StringeeClient

import {StringeeClient, StringeeClientListener} from 'stringee-react-native-v2';
...
const stringeeClient = new StringeeClient();
let chatRequest = null;
let agentConversation = null;

// Listen for the StringeeClient event
const stringeeClientListener = new StringeeClientListener();
// Invoked when the StringeeClient is connected
stringeeClientListener.onConnect = (stringeeClient, userId) => {
   console.log('onConnect: ', userId);
};
// Invoked when the StringeeClient is disconnected
stringeeClientListener.onDisConnect = (stringeeClient) => {
   console.log('onDisConnect');
};
// Invoked when the StringeeClient connection fails
stringeeClientListener.onFailWithError = (stringeeClient, code, message) => {
   console.log('onFailWithError: ', message);
};
// Invoked when your token is expired
stringeeClientListener.onRequestAccessToken = (stringeeClient) => {
   console.log('onRequestAccessToken');
};
// Invoked when conversation or message update
stringeeClientListener.onObjectChange = (stringeeClient, objectType, objectChanges, changeType) => {
   console.log('onObjectChange: ', objectType, objectChanges, changeType);
};
// Invoked when the client receives chat request
stringeeClientListener.onReceiveChatRequest = (stringeeClient, request) => {
   chatRequest = request;
   console.log('onReceiveChatRequest', JSON.stringify(request));
};
// Invoked when the client receives transfer chat request
stringeeClientListener.onReceiveTransferChatRequest = (stringeeClient, request) => {
   chatRequest = request;
   console.log('onReceiveTransferChatRequest', JSON.stringify(request));
};
// Invoked when a chat request time out for answer and route to next agent
stringeeClientListener.onTimeoutAnswerChat = (stringeeClient, request) => {
   console.log('onTimeoutAnswerChat', JSON.stringify(request));
};
// Invoked when the conversation is ended
stringeeClientListener.onConversationEnded = (stringeeClient, convId, endedby) => {
   console.log('onConversationEnded: ', convId, endedby);
};
stringeeClient.setListener(stringeeClientListener);

Connect to Stringee

const token = 'PUT YOUR TOKEN HERE';
...
stringeeClient.connect(token);

Step 2: Accept/ Reject

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

Accept

To accept the chat request, call the following method on the ChatRequest object:

if (!chatRequest) {
   return;
}
chatRequest.acceptChatRequest().then(() => {
   console.log('acceptChatRequest success');
    // if accept success, you can get conversation to start chatting
   stringeeClient.getConversationById(chatRequest.convId).then(conversation => {
      agentConversation = conversation;
      console.log('getConversationById', JSON.stringify(agentConversation));
   }).catch(console.log);
}).catch(console.log);

After the chat request is accepted, call stringeeClient.getConversationById(...) with the conversation ID from the request.

Reject

To reject the chat request, call the following method on the ChatRequest object:

if (!chatRequest) {
   return;
}
chatRequest.rejectChatRequest().then(() => {
   console.log('rejectChatRequest success');
}).catch(console.log);

Step 3: Messages

Follow this instruction Messages

Step 4: End a live chat conversation

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

if (!agentConversation) {
   return;
}
agentConversation.endChat().then(() => {
   console.log('endChat success');
}).catch(console.log);

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 StringeeClient object:

import {LiveChatTicketParam} from 'stringee-react-native-v2';

const liveChatTicketParam = new LiveChatTicketParam();
liveChatTicketParam.name = 'CUSTOMER_NAME';
liveChatTicketParam.email = 'CUSTOMER_EMAIL';
liveChatTicketParam.phone = 'CUSTOMER_PHONE';
liveChatTicketParam.note = 'TICKET_DESCRIPTION';
stringeeClient.createLiveChatTicket('YOUR_WIDGET_KEY', liveChatTicketParam).then(() => {
   console.log('createLiveChatTicket success');
}).catch(console.log);

Chat Transcript

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

conversation.sendChatTranscript('EMAIL', 'DOMAIN').then(() => {
   console.log('sendChatTranscript success');
}).catch(console.log);

Sample

You can view the latest React Native Live Chat sample on GitHub: LiveChatSample

Suggestions

Getting started with Stringee Live Chat API

Prepare

Install stringee-react-native package

Setup

Android

iOS

Customer

Step 1: Connect to Stringee Server

Step 2: Get chat profile

Step 3: Generate access token for customers

Step 4: Start a live chat conversation

Step 5: Messages

Step 6: End a live chat conversation

Agent

Step 1: Connect to Stringee Server

Step 2: Accept/ Reject

Accept

Reject

Step 3: Messages

Step 4: End a live chat conversation

Extra

Create a ticket when live chat is unavailable

Chat Transcript

Sample