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
You can find Qiscus Chat SDK requires minimum on this table:
| Browser | Supported Version |
|---|---|
| Internet Explorer | 11 or later |
| Edge | 17 or later |
| Chrome | 24 or later |
| Firefox | 21 or later |
| Safari | 11 or later |
| Opera | 15 or later |
| iOS Safari | 6 or later |
| Android Browser | KitKat 4.4 or later |
To integrate your app with Qiscus Chat SDK, you can add qiscus-sdk-core files into your html file. Here is how to do that:
<html lang="en"><head> <meta charset="UTF-8"></head><body> <script src="https://unpkg.com/qiscus-sdk-core"></script></body></html>Or if you are using npm as your project dependencies management, you can just install Qiscus Chat SDK from npm. Here is how to do that:
npm install --save qiscus-sdk-coreYou can set the version of Qiscus Chat SDK in npm:
npm install qiscus-sdk-core@latestStep 3: Initialization Qiscus Chat SDK
You need to initiate your App ID for your chat App before carry out to Authentication. This initialization only need to be done once when your app first loaded. Initialization can be implemented in the initial startup. Here is how you can do that:
const qiscus = new QiscusSDKCore()window.addEventListener('DOMContentLoaded', function () { qiscus.init({ AppId: 'QISCUS_SDK_APP_ID' })})The initialization should be called once. If you are using javascript library or framework like React, Angular or Vue, it is best to initiate Qiscus Chat SDK on the top most component of your application
Step 4: Authenticate to Qiscus
To use Qiscus Chat SDK features, a user firstly need 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:
qiscus.setUser('userId', 'uniqueKey', 'displayName', 'https://someurl.com/avatar.png', {}) .then(function (authData) { // On success }) .catch(function (error) { // On error })Where:
userId(string, unique): A user identifier that will be used to identify a user and used whenever another user need 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 sensitiveuserKey(string): userKey for authentication purpose, so even if a stranger knows your user Id, he/she cannot access the user data.username(string): Username for display name inside Chat Room purposes.avatarURL(string, optional): to display user's avatar, fallback to default avatar if not provided.extras(string, optional): to give additional information (metadata) to user, which consist key-value, for example key:position, and value: engineer
For further detail you might refer to Authentications link.
Step 5: Create 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 chatTarget 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.
qiscus.chatTarget('userId') .then(function (room) { // On success }) .catch(function (error) { // On error })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:
qiscus.sendComment('roomId', 'Hi') .then(function (comment) { // On success }) .catch(function (error) { // On error })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 newMessagesCallback event. This event is triggered whenever users send a message
// Callback receive commentqiscus.init({ AppId: , options: { newMessagesCallback(messages) { var message = messages[0] // Do something with message } }});For further details about message, you can find at Message section. and Event handler section.