Getting Started
This section help you to start building your integration, so that you can send your first message.
Step 1: Get Your App ID
First of all, you need to create your application (App ID) in dashboard, by accessing Qiscus Chat Dashboard.
You can create more than one App ID within a single account. For further information regarding multiple applications in single account.
Step 2: Install Qiscus Chat SDK
Qiscus Chat SDK requires minimum Android API 16 (Jelly Bean). To integrate your app with Qiscus, it can be done in 2 steps:
First, you need to add URL reference in your .gradle project. This is a guide for .gradle to get Qiscus Chat SDK from the official repository:
allprojects { repositories { ... maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" } } }Second, you need to add SDK dependencies inside your app .gradle. Then, you need to synchronise it to compile the Qiscus Chat SDK for your app.
dependencies { ... implementation 'com.qiscus.sdk:chat-core:1.6.1'}Step 3: Initialization Qiscus Chat SDK
You need to initiate your App ID for your chat app before you carry out to authentication. This initialization only needs to be done once in the app's lifecycle. Initialization can be implemented in the initial startup. Here is the example on how you can do that:
public class SampleApp extends Application { public void onCreate() { super.onCreate(); QiscusCore.setup(this, APPID); }The initialization should be called once across an Android app . You should usually put in application class.
Step 4: Authenticate to Qiscus
To use Qiscus Chat SDK features, first, user needs to authenticate to Qiscus Server. This authentication is done by calling setUser() function. This function will retrieve or create user credential based on the unique userId, for example:
QiscusCore.setUser(userId, userKey) .withUsername(username) .withAvatarUrl(avatarUrl) .withExtras(extras) .save(new QiscusCore.SetUserListener() { public void onSuccess(QiscusAccount qiscusAccount) { //on success } public void onError(Throwable throwable) { //on error });Where:
userId(string): a user identifier that will be used to identify a user and used whenever another user needs to chat with this user. It can be anything, whether is is user's email, your user database index, etc. As long as it is unique and a string. This value is case sensitive.userKey(string): a user key for authentication purpose. So, even if a stranger knows your userId, he cannot access the user data.username(string): a username is used as a display name inside chat room.avatarURL(string, optional): to display user's avatar, fallback to default avatar if not provided.extras(JSON, optional): to give additional information (metadata) to user, which consist key-value, for example key:position, and value: engineer
For further details, you might see on Authentications section.
Step 5: Create a Chat Room
There are three Chat Room types in Qiscus Chat SDK:
- 1-on-1 Chat Room
- Group Chat Room
- Channel Chat Room
In this section, we will use 1-on-1 Chat Room. We assume that you already know a targeted user you want to chat with. To start a conversation with your targeted user, you can call chatUser() method. Qiscus Chat SDK, then, will serve you a new chat room, asynchronously. When the room is successfully created, Qiscus Chat SDK will return a chat room package through onSuccess listener.
QiscusApi.getInstance().chatUser(userId, extras) .subscribeOn(Schedulers.io()) //need to run this task on IO thread .observeOn(AndroidSchedulers.mainThread()) //deliver result on main thread or UI thread .subscribe(qiscusChatRoom -> { // on success }, throwable -> { // on error })Where:
userId(string) : a user identifier that will be used to identify a user and used whenever another user needs to chat with this user. It can be anything, whether is user's email, your user database index, etc. as long as it is unique and a string. This value is case sensitiveextras(JSON, optional) : metadata that can be as additional information to chat room, which consists key-value, for example, key: background, and value: red
Make sure that your targeted user has been registered in Qiscus Chat SDK. Otherwise you will receive error.
Step 6: Send Message
You can send any type of data through Qiscus Chat SDK, in this section let's send a "Hi" message, with type value is text. You need to pass roomId and the message value, for example:
String message = "Hi"QiscusComment qiscusMessage = QiscusComment.generateMessage(roomId, message)QiscusApi.getInstance().sendMessage(qiscusMessage) .subscribeOn(Schedulers.io()) // need to run this task on IO thread .observeOn(AndroidSchedulers.mainThread()) // deliver result on main thread or UI thread .subscribe(qiscusChatRoom -> { // on success }, throwable -> { // on error });Where:
roomId(long): chat room id, you can get this id in chat room objectmessage(string): text that you send to other participanttype(string): message type, that you can define freely, there are reserved rich messages type, for example: text, file_attachment, account_linking, buttons, button_postback_response, reply, system_event, card, custom, location, contact_person, carousel. These type have been taken, if you use it and custom your structured data, you may face your structured data will not work, these type for bot API, hence you need define other type name.
You can define any type and data, and render it to your own customised UI.
Messages can be received by the recipient target through a onMessageReceived event. This event is triggered whenever users send a message.
Class for this event is com.qiscus.sdk.event.QiscusCommentReceivedEvent, you can create a method that listens with this class type, for example:
public void onMessageReceived(QiscusCommentReceivedEvent event) { event.getQiscusComment(); // to get the message}For further details about message, you can find at Message section and Event handler section.