QuickBlox Documentation

QuickBlox provides powerful Chat API and SDK to add real-time messaging and video calls to your web and mobile apps. Learn how to integrate QuickBlox across multiple platforms and devices. Check out our detailed guides to make integration easy and fast.

Setup

Learn how to add and configure QuickBlox SDK for your app.

Follow the instructions below to ensure that QuickBlox JavaScript SDK runs smoothly with your app.

Before you begin

Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.

Browsers support

Edge

Firefox

Chrome

Opera

Node.js

Safari

14+

52+

50+

36+

6+

11.1+

Get application credentials

QuickBlox application includes everything that brings messaging right into your application - chat, video calling, users, push notifications, etc. To create a QuickBlox application, follow the steps below:

  1. Register a new account following this link. Type in your email and password to sign in. You can also sign in with your Google or Github accounts.
  2. Create the app by clicking the New app button.
  3. Configure the app. Type in the information about your organization into corresponding fields and click the Add button.
  4. Go to Dashboard => YOUR_APP => Overview section and copy your Application ID, Authorization Key, Authorization Secret, and Account Key.

Requirements

The minimum requirements for QuickBlox JavaScript SDK are:

  • JavaScript es5.

Install QuickBlox SDK into your app

There are 3 ways to integrate QuickBlox JavaScript SDK into your app.

Dependencies for browser

Install QuickBlox library dependencies for browser to establish communication with QuickBlox server. Simply connect the JS file as a normal script. Once it is done, a window scoped variable called QuickBlox is created.

<script src="https://unpkg.com/[email protected]/quickblox.min.js"></script>

Node.js and NPM integration

📘

To manage project dependencies Node.js and npm must be installed

  1. Open a terminal and enter the commands below in your project path.
npm install quickblox --save
  1. To be able to work with QuickBlox library, connect it as follows:
var QB = require('quickblox');
// OR to create many QB instances
var QuickBlox = require('quickblox').QuickBlox;
var QB1 = new QuickBlox();
var QB2 = new QuickBlox();

Bower and RequireJS

📘

To manage project dependencies Bower and Require JS must be installed.

Install the SDK through Bower as follows:

bower install quickblox --save

Initialize QuickBlox SDK

Initialize the framework with your application credentials. Pass Application ID, Authorization Key Authorization Secret, and Account Key to the init() method.

var APPLICATION_ID = "41";
var AUTH_KEY = "lkjdueksu7392kj";
var AUTH_SECRET = "iiohfdija792hj";
var ACCOUNT_KEY = "sdjfnksnlk2bk1k34kb";
var CONFIG = { debug: true };

QB.init(APPLICATION_ID, AUTH_KEY, AUTH_SECRET, ACCOUNT_KEY, CONFIG);

Parameters

Description

APPLICATION_ID

Application identifier.

AUTH_KEY

Authorization key.

AUTH_SECRET

Authorization secret.

ACCOUNT_KEY

Account key. Required to get actual Chat and API endpoints for the right server.

CONFIG

(optional) SDK configuration settings for custom endpoints, chat connecting, WebRTC, etc.

You can set the following fields using the CONFIG object:

Parameters

Description

endpoints

Custom endpoints configuration.

streamManagement

Stream management configuration.

webrtc

WebRTC configuration.

chatProtocol

Chat protocol configuration. Set 1 to use BOSH, set 2 to use WebSockets. Default: WebSocket.

debug

Custom endpoints configuration.

Initialize with existing token

You can initialize the SDK with an existing QuickBlox token. It can be interesting in cases when you build a big system and you have the server side which generates QuickBlox tokens.

var sessionToken = '1b785b603a9ae88d9dfbd1fc0cca0335086927f1';
var appId = 3451;
var accountKey = 'sdjfnksnlk2bk1k34kb';
var config = { debug: false };

QB.init(sessionToken, appId, null, accountKey, config);

Custom endpoints

To connect QuickBlox SDK to the custom server, you should specify api and chat endpoints using the CONFIG object and pass it to the init() method.

var APPLICATION_ID = "41";
var AUTH_KEY = "lkjdueksu7392kj";
var AUTH_SECRET = "iiohfdija792hj";
var ACCOUNT_KEY = "sdjfnksnlk2bk1k34kb";
var CONFIG = {
  endpoints: {
    api: "apicustomdomain.quickblox.com", // set custom API endpoint
    chat: "chatcustomdomain.quickblox.com", // set custom Chat endpoint
  },
  chatProtocol: {
    active: 2, // set 1 to use BOSH, set 2 to use WebSockets (default)
  },
  /**
   * set { mode: 1 } or true to output to console,
   * set { mode: 2, file: 'log.txt' } to output to file,
   * set "false" to not output
   */
  debug: { mode: 1 },
};
QB.init(APPLICATION_ID, AUTH_KEY, AUTH_SECRET, ACCOUNT_KEY, CONFIG);

Set custom endpoints using the endpoints field of the CONFIG object:

Parameters

Description

api

API endpoint.

chat

Chat endpoint

📘

For Basic, Startup, and Growth plan users

- Make sure to set ACCOUNT_KEY to get all correct endpoints.
- Make sure to leave api and chat fields empty to provide a smooth migration between servers.

📘

For Enterprise plan users

Contact our sales team to get api and chat values.

Enable logging

Logging functionality allows you to keep track of all events and activities while running your app. As a result, you can monitor the operation of the SDK and improve the debug efficiency.

Set the debug mode in the CONFIG object and then call the init() method.

var APPLICATION_ID = "41";
var AUTH_KEY = "lkjdueksu7392kj";
var AUTH_SECRET = "iiohfdija792hj";
var ACCOUNT_KEY = "sdjfnksnlk2bk1k34kb";
var CONFIG = {
  // other settings
  /**
   * set { mode: 1 } or true to output to console,
   * set { mode: 2, file: 'log.txt' } to output to file,
   * set "false" to not output
   */
  debug: { mode: 1 }
};
QB.init(APPLICATION_ID, AUTH_KEY, AUTH_SECRET, ACCOUNT_KEY, CONFIG);

There are 3 debug modes:

Debug modes

Description

0

Turns off logging output.

1

Enables logging to the browser console with console.log() function (default value).

2

Enables logging to a file. Set the file in the file field. Works only on Node.js, in case of server implementations.

Message carbons

Message carbons functionality allows for multi-device support. Thus, all user messages get copied to all their devices so they could keep up with the current state of the conversation. For example, a User A has phone running conversations and desktop running conversations. User B has desktop running conversations. When User B sends a message to User A, the message shows on both the desktop and phone of User A.

📘

Message carbons are always enabled.

Stream management

Stream management has two important features Stanza Acknowledgements and Stream Resumption:

  • Stanza Acknowledgements is the ability to know if a stanza or series of stanzas has been received by one's peer. In other words, a reply is requested on every sent message. If the reply is received, the message is considered as delivered.
  • Stream Resumption is the ability to quickly resume a stream that has been terminated. So once a connection is re-established, Stream Resumption is executed. By matching the sequence numbers assigned to each Stanza Acknowledgement a server and client can verify which messages are missing and request to resend missing messages.
var CONFIG = {
  streamManagement: {
    enable: true
  }
};

📘

By default, stream management functionality is disabled. Make sure to enable it using the CONFIG parameter when calling init() method. Review Initialize QuickBlox SDK section for more details.

Custom ICE servers

You can customize a list of ICE servers. By default, WebRTC module will use internal ICE servers that are usually enough, but you can always set your own. WebRTC engine will choose the TURN relay with the lowest round-trip time. Thus, setting multiple TURN servers allows your application to scale-up in terms of bandwidth and number of users.

var CONFIG = {
  webrtc: {
    iceServers: [
      {
        urls: "stun:stun.randomserver.example",
        username: "stun_login",
        credential: "stun_password"
      },
      {
        urls: "turn:turn.randomserver.example",
        username: "turn_login",
        credential: "turn_password"
      }
    ]
  }
};

Updated about a month ago


What's Next

Authentication

Setup


Learn how to add and configure QuickBlox SDK for your app.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.