Qiscus SDK helps you build Web Chat Application easy and fast. It uses qiscus server backend for the API.
There's two version of the SDK. The SDK Core Only version which you can use to build a custom chat app without opinionated view layer.
The other version is the one with View layer already integrated in it (in this case we're using VueJs, other view layer already on TODO list).
You can download files you need by navigating to the release section.
Register on www.qiscus.com/dashboard using your email and password and then create new application
You should create one application per service, regardless of the platform. For example, an app released in Android, iOS or Web would require only one application to be created in the Dashboard.
All users within the same qiscus application are able to communicate with each other, across all platforms. This means users using iOS, Android, web clients, etc. can all chat with one another. However, users in different Qiscus applications cannot talk to each other.
Done! Now you can use the APP_ID into your apps and get chat functionality by implementing qiscus into your app.
qiscus SDK let you add a chat widget directly into your existing HTML web pages. You just need to include the javascript and css files from the build directory. And you also need to append <div id="qiscus-widget"></div> tag before closing body tag. Here's sample HTML:
You can just copy and paste this into your html file and it'll work directly.
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
<link rel=stylesheet href=https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css>
<link rel="stylesheet" type="text/css" href="https://s3-ap-southeast-1.amazonaws.com/qiscus-sdk/web/v2.4.0/css/qiscus-sdk.2.4.0.css">
<!-- add this CDN for emojione if you intend to support emoji -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/emojione/2.2.7/lib/js/emojione.min.js"></script>
</head>
<body>
<div id="qiscus-widget"></div>
<script src="https://s3-ap-southeast-1.amazonaws.com/qiscus-sdk/web/v2.4.0/js/qiscus-sdk.2.4.0.js"></script>
<script>
// let's setup options for our widget
QiscusSDK.core.init({
AppId: 'DRAGONGO',
options: {
// When we're success login into qiscus SDK we'll have a 1-on-1 chat to [email protected]
// You can change this to any user you have on your AppId, e.g: contact@your_company.com, etc
loginSuccessCallback(data) { QiscusSDK.core.UI.chatTarget('[email protected]') },
// function below will be called when there's new message
newMessagesCallback(data) { console.log("new message : ", data) }
}
});
// login to qiscus
QiscusSDK.core.setUser('[email protected]', 'password', 'Qiscus Demo');
// render the widget
QiscusSDK.render();
</script>
</body>
</html>We're using two CDN here, one for emoji support and one for the icon, in this case we're using FontAwesome. The emojione is optional though.
If you already registered for your own AppId, just replace dragongo with your own AppId. In the example above we automatically open a chat roow with [email protected] assuming that user already registered on dragongo AppId, if the user is not registered then it will be failed.
On the code snippet above, we can pass several callbacks to init options, in the example we're using loginSuccessCallback which will be called when login is success. It'll automatically open 1-1 chat room with [email protected]. There's also newMessagesCallback where in the example it just log what the messages are. After that we render the widget into our page by calling QiscusSDK.render()
We can initialize qiscus SDK by using this line of code:
QiscusSDK.core.init({
AppId: 'DRAGONGO',
options: {
// When we're success login into qiscus SDK we'll have a 1-on-1 chat to [email protected]
// You can change this to any user you have on your AppId, e.g: contact@your_company.com, etc
loginSuccessCallback(data) { QiscusSDK.UI.chatTarget('[email protected]') },
// function below will be called when there's new message
newMessagesCallback(data) { console.log("new message : ", data) }
}
});
Here are list of available callbacks:
- loginSuccessCallback
- loginErrorCallback
- newMessagesCallback
- chatRoomCreatedCallback
- groupRoomCreatedCallback
- headerClickedCallback
After we initialize the SDK, we need to set login data for current user by using this code:
QiscusSDK.core.setUser('[email / unique identifer]', '[password]', '[Display Name]');
You can use the previous login code to update your data:
QiscusSDK.core.setUser('email', 'key', 'username', 'avatar_url');
emailemail used by currently logged in userkeysecret key for current userusernameusername to be displayed to other participantavatar_urluser avatar, fallback to default avatar if not provided
To create a 1-to-1 chat use this code:
QiscusSDK.core.chatTarget('[email / unique identifier]')
QiscusSDK.core.createGroupRoom (name, ...emails)
where email(s) is in the type of array
QiscusSDK.core.chatGroup('group_room_id')
Here's a video showing how you can set up sample app for qiscus SDK
In case you don't want to have the sdk displaying on a widget view, we can put the Chat inside a container by setting mode to wide on init as a parameter like this example.
QiscusSDK.core.init({
AppId: 'DRAGONGO',
mode: 'wide',
options: {
// When we're success login into qiscus SDK we'll have a 1-on-1 chat to [email protected]
// You can change this to any user you have on your AppId, e.g: contact@your_company.com, etc
loginSuccessCallback(data) { QiscusSDK.UI.chatTarget('[email protected]') },
// function below will be called when there's new message
newMessagesCallback(data) { console.log("new message : ", data) }
}
});
You can also enable / disable avatar by passing avatar options.
The code above will put qiscus chat inside a container. Here's a working example on codepen
The widget is built using vuejs and divided into several components. We also use fontawesome for the icon, so you can target fontawesome css class directly. You can change the appearance of the widget by using these css selectors below.
Widget components have namespaces of qcw...
| css properties | description |
|---|---|
| .qcw-trigger-button | Button for toggling the chat window |
| .qcw-container | Widget Window Wrapper div |
| .qcw-header | Widget Header containing active chat title |
| ul#messages__comments | Messages list container |
| .qcw-comment-form | Comment Form container |
| .qcw-comment-form textarea | Comment Text Input Field |
| .qcw-comment-form i | Comment Form icons (paperclip and paper-plane icon) |
| .comment-form i | Comment Form icons (paperclip and paper-plane icon) |