Key Concepts

Learn about basic QuickBlox concepts to simplify the integration with QuickBlox.


QuickBlox Dashboard enables you to create new apps and manage your existing apps using Chat, Content, Push Notifications, Custom Objects, and Users modules. Get your application credentials (Application ID, Authorization Key, Authorization Secret, and Account Key) from here to launch SDKs. For backend integration use API Keys.


QuickBlox application includes all you need to add real-time messaging and voice/video calling to your app including users, push notifications, file storage, etc. A user logs in to the app, reviews a list of dialogs, chooses a dialog, or creates their own, writes a message, and sends it to the dialog. Along with that, they can view chat history, configure pushes, and many more.

Each QuickBlox application has a unique Application ID used for the integration with your app. Along with Application ID you get Authorization Key, Authorization Secret, and Account Key required for SDKs initialization, or API Keys for backend. These data are stored in the QuickBlox server database and can be subsequently identified on the server as a result of the successful initialization procedure.


Keep in mind the points below:

All users in your QuickBlox application can communicate across multiple platforms. In other words, your iOS, Android, or web users can communicate with each other.

Each QuickBlox application is associated with its own users' database. Thus, users are not mixed up between different applications.

Only one QuickBlox application can be integrated into your app. This means that there is no need to create a single QuickBlox application for each platform individually.

Auth & API Keys

TypePrivilegesRecommended to use
Authorization Key + Authorization SecretAllows to create application/user session tokenIn client side code during development
API KeyAllows to perform actions on QuickBlox serverIn server side code


QuickBlox API can be accessed either with session token or with API key.

To access QuickBlox API a user needs to authenticate your application with the QuickBlox server. A token-based authentication is used to provide secure access to QuickBlox API. When the authenticity is verified, the server responds to the request with the access token that becomes a part of each subsequent request to the QuickBlox server.

QuickBlox does not handle user management. QuickBlox offers only basic user management, for secure production implementation you must handle user registration and login at your end. Once the user is logged into your app/site, you can log in the user to QuickBlox programmatically. So the user does not ever directly login to QuickBlox.

A token is a piece of data identifying a user or application and providing temporary access to QuickBlox Server API. The token is valid only within the session it was generated. The session gets expired in 2 hours after the last request to the Server API.

There are two types of tokens: application session token and user session token. The application session token is limited to read-only permissions preventing changes to application data while the user session token is not restricted in permissions and allows for making edits to application data.

Session Token TypeDescription
Application session tokenThis kind of access token is needed to read the app data. Has only READ access to resources. The expiration time after the last Server API request is 2 hours.
User session tokenThe user token is the most commonly used type of token. This kind of access token is needed any time the app calls an Server API to read, modify or write a specific user's data on their behalf. Has READ/WRITE access to resources. The expiration time after the last API request is 2 hours.


Users are managed via the User module. A user is the one who can access all chat features of a QuickBlox application with their own unique ID. QuickBlox server authorizes a user by the user ID. When the user sends a login request to the server, the server queries the database to check for a match upon the request for connection.

A user can be assigned multiple tags. Set up user tags and address users separately in your app through the Server API or Dashboard. Tags can be managed via the user profile.

There are two user roles in QuickBlox API:

  • Account owner is a user who has registered the application. A user with an administrator role who has access privileges that enable them to use all functions for application management, monitoring, and viewing information. This user can access each application of the account. The account owner is the one who signs up to QuickBlox Dashboard and can manage a Dashboard account. The account user is also an API user.
  • Application user is a user having the access to QuickBlox Server API and authorized to make requests to the QuickBlox server. An application user is the one who signs in to the QuickBlox application with their email, login, and password via the Server API.
PermissionAccount ownerApplication user
Create user++
View user info++
Update themselves++
Update other users+-
Delete themselves++
Delete other user+-


QuickBlox Chat runs over the XMPP protocol. To be able to use it, you should establish a real-time connection with the QuickBlox server. If the connection to the server is lost, the application gets automatically connected to the Chat server in order to receive messages in real-time.

Dialogs are the basis of chat activity. Users send messages to the dialog from where they get distributed to the opponent users. There are 3 dialog types:

  • Private. A dialog for two participants. Created automatically upon the first message.
  • Group. A dialog involving more than two participants. To start a group dialog, the user should create a group dialog and add a new participant in the new group dialog. A user who is invited to the group dialog can either accept or decline the invitation.
  • Public. A dialog involving more than two participants. Any user can access this dialog without a preliminary invitation.

Messages are data pools that get published in the dialogs. They can contain any data - arrays, objects, numbers, and strings. They also can acquire read and delivered statuses. There are supported three types of messages:

  • Text. By default, a message is considered as text.
  • Media. There are available any types of attachments, audio, video, image, or other.
  • Custom. A message can be extended with custom data such as location coordinates.


Your application should be constantly connected to the Chat server to ensure that messages are always delivered efficiently.

Video Calling

In addition to messaging, QuickBlox allows you to add high-quality video calls to your apps. Our video calling API is built on WebRTC principles providing a simplified, secure communication channel including audio and video for web and mobile apps.

The communication is happening between peers representing camera devices. There are two peer types:

  • Local peer is a device running the app right now.
  • Remote peer is an opponent device.

Establishing real-time video communication between two peers involves 3 phases:

  • Signaling. At this phase, the peers’ local IPs and ports where they can be reached (ICE candidates) are exchanged as well as their media capabilities and session control messages.
  • Discovery. At this phase, the public IPs and ports at which endpoints can be reached are discovered by STUN/TURN server.
  • Establishing a connection. At this phase, the data are sent directly to each party of the communication process.

The signaling is implemented over the XMPP protocol using QuickBlox Chat. So before starting to work with the Video Calling API, a connection to the QuickBlox Chat server is required to be established first.

To call users, you should initiate a call. As a result, a call session is created. A call session represents a room for real-time audio/video, data, and/or screen-share session, and is the basic building block for your video calling app.

To receive events associated with the call session and peer connection, the event listener is required to be set up. Thus, when your app gets disconnected from the server and tries to re-establish the XMPP connection with the QuickBlox server, the server notifies the app of the event through the event listener.

Each particular audio/video call has a unique session ID. This allows you to have more than one independent audio/video calls. QuickBlox SDK supports one-to-one calls and group calls with up to four peers.

If you want to make group calls, you can do it between a few users. Using WebRTC your device connects with each user in the call. It means that each device must handle as many connections as there are users in the current call.

This table shows how many connections your device must establish to make a group call with a different number of users in the call.

Users in CallConnections numberPer user
22 connections2 connections
36 connections4 connections
412 connections6 connections
520 connections8 connections

So as you can see, to make a call with 4 other participants each device has to handle 8 different connections to send and receive audio and video tracks to each other call participant. It requires high-performance devices.

The other solution we provide requires only 1 output and 1 input connection to make up to 10 users multi-user call.


Please use this WebRTC Video Calling to make the Group Calls with 4 or fewer users. Because of Mesh architecture we use for multi-point where every participant sends and receives its media to all other participants, the current solution supports group calls with up to 4 people.

You can also set up a connection with up to 12 people in the call at the same time. This feature is available only for Enterprise plans only. If you need to make group calls with more than 4 users, please contact us for more details on the feature.

Video Conference

QuickBlox provides a Multiparty Video Conferencing solution allowing to set up a video conference between 10-12 people. It is built on top of WebRTC SFU technologies.

To call users, you should create a conference session. To process events associated with the session state, the event listener is required to be implemented. Once a session is created, you can interact with the video conferencing API.

Each particular conference session has a unique session ID. This allows you to have more than one independent conference calls.

QuickBlox Video Conferencing API is based on top of regular Video Calling API, so we recommend getting familiar with it first.


This feature is available for customers on the Enterprise plan only. Take advantage of Enterprise features to unlock new value and opportunities for users. For more information and if you want to request a Demo, please contact us by mail: [email protected].


With the QuickBlox content module, a user can store rich chat attachments, app content, and settings without having to re-publish it.

A file is a dedicated entity within the system. It has a unique file ID that is generated automatically by the server upon file creating. The file gets uploaded to a cloud storage. After a file is declared as uploaded, a URL of the file is returned by the server. Following the URL, the file can be subsequently downloaded. There are two types of file URLs that can be obtained:

  • Public URL allows anyone to access the file, no authorization token is needed.
  • Private URL can be accessed only by the QuickBlox user with a session token.

You can upload, delete, edit files as well as view the list of all available files via the Dashboard or Server API requests.

Push Notifications

Our SDK allows you to build an app that can receive push notifications. As a result, your users will always be informed with timely content even though the app is closed or running in the background. QuickBlox provides a way to set up offline messaging for your app. This means that a push notification will be automatically delivered to the opponent device only when it is fully offline.

Push notifications for your apps are sent using FCM (Google's Firebase Cloud Messaging) or APNs (Apple Push Notification service). When a message is sent to the QuickBlox server through the SDK, the server communicates with APNs or FCM regarding the message. The logic is built around two main concepts:

  • Subscription. A device should be subscribed to APNs and FCM services. The subscription parameters (device id, private id, app id, notification channel, etc.) are sent by the QuickBlox server within a push subscription request to the Google server and Apple server. Once the device is subscribed for the services, the APNs or FCM delivers a notification to it.

  • Event. The event is a dedicated entity within the system. Each event has a unique event ID generated automatically by the server after event creation. Once the event is created, the server initiates sending a push notification.

Custom Objects

QuickBlox Custom Objects module represents a key-value storage enabling you to create any data structure using the Dashboard or Server API. There are two key concepts in Custom Objects:

  • Class represents your schema and contains field names and types.
  • Record represents data you put into your schema.

You will be able to create classes containing different field types (integer, string, float, boolean, etc.) as well as set relations between different classes. You can also set access control for the class to define who can access the records in the class and make edits to it.

Custom Objects module provides flexibility to define any data structure (schema) you need, build one-to-many relations between schemas and control permissions for all operations made on data. The schema is defined in QuickBlox Dashboard.

There are two key concepts in Custom Objects:
- Class represents your schema and contains field names and types.
- Record represents data you put into your schema.

Class and Record are similar to table and row in relational database. Every class in Custom Object module comes with five mandatory predefined fields: _id, user_id, parent_id, created_at, and updated_at.

Allowed data types: Integer (or Array of Integer); String (or Array of String); Float (or Array of Float); Boolean (or Array of Boolean); Location (Array of [<longitude>, <latitude>]); File; Date.

For example, you want to store a simple calendar that stores the event title and event date. In this case, you can create a Calendar class with following fields: event_title and event_date.

Calendar records will have the following structure:

Field nameType

Calendar data will look like:

5d866b53a28f9a5ad51cb56296753878nullMeet John2019-12-25T14:00:00Z15766297611576629761
5d866b53a28f9a5ad51cb56396753878nullVisit my dentist2019-09-25T15:00:00Z15772824001577282400


It is possible to create a relation between objects of two different classes via _parent_id field.

For example, we have the class Rating that contains score, review, and comment fields. We also have a Movie class. So we can create a record of class Rating that will point to the record of the class Movie via its _parent_id field, so the _parent_id field will contain the ID of record from class Movie.


This is not a simple soft link. This is actually a hard link. When you delete the Movie class record then all its children (records of class Rating with _parent_id field set to the Movie class record ID) will be automatically deleted as well.


If you need to retrieve all children, you can retrieve records with the filter _parent_id=<id_of_parent_class_record>.



Access control list available only for Custom Objects module.

Access control list (ACL) is a list of permissions attached to some object. An ACL specifies which users have access to objects as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. ACL models may be applied to collections of objects as well as to individual entities within the system hierarchy.


Here are actions you can perform on record entity:

CreateCreate a record.
ReadRetrieve and read the info about the chosen record.
UpdateUpdate any parameter for the chosen record (only those parameters that can be set by the user can be updated).
DeleteDelete a record.

Permission levels

QuickBlox permission schema contains five permissions levels:

Permission levelDescription
Open (open)Such permission schema means that any user within the application can access the record/records in the class and is allowed to perform an action with the current permission level.
Owner (owner)Owner permission level means that only Owner (a user who created a record) is allowed to perform action with the current permission level.
Not allowed (not_allowed)No one (except for the Account Administrator) can make a chosen action.
Open for groups (open_for_groups)Users having a specified tag/tags (see more info about how to set tags for the user in Users section) will be included in the group that is allowed to perform an action with the current permission level. The current permission level can consist of one or several groups (number of groups is not limited). Tags can be added/deleted in the user’s profile.
Open for user ids (open_for_users_ids)Only users that are specified in the permission level can make a required action with a record. One or several users can be specified (the number of users is not limited).