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.

Before you begin

  1. Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.
  2. Register a QuickBlox account. This is a matter of a few minutes and you will be able to use this account to build your apps.
  3. Configure QuickBlox SDK for your app. Check out our Setup page for more details.
  4. Create a user session to be able to use QuickBlox functionality. See our Authentication page to learn how to do it.
  5. Connect to the Chat server. See our Connection page to learn how to do it.

Dialog types

All chats between users are organized in dialogs. There are 3 types of dialogs:

  • private dialog - a dialog between 2 users.
  • group dialog - a dialog between the specified list of users.
  • public dialog - an open dialog. Any user from your app can be joined to it.

You need to create a new dialog and then use it to chat with other users. You also can obtain a list of your existing dialogs.

Create dialog

To create a private dialog, you need to set the dialog type field to private and ID of the opponent you want to create a chat with.

let dialog = QBChatDialog(dialogID: nil, type: .private)
dialog.occupantIDs = [34]
QBRequest.createDialog(dialog, successBlock: { (response, createdDialog) in

}, errorBlock: { (response) in
    
})
QBChatDialog *dialog = [[QBChatDialog alloc] initWithDialogID:nil type:QBChatDialogTypePrivate];
dialog.occupantIDs = @[@34]; // an ID of opponent
[QBRequest createDialog:dialog successBlock:^(QBResponse * _Nonnull response, QBChatDialog * _Nonnull createdDialog) {
        
} errorBlock:^(QBResponse * _Nonnull response) {
        
}];

To create group dialog for a predefined number of occupants, you need to set the dialog type field to group and IDs of opponents you want to create a chat with.

let chatDialog = QBChatDialog(dialogID: nil, type: .group)
chatDialog.name = "New group dialog"
chatDialog.occupantIDs = [34, 45, 55]
        
QBRequest.createDialog(chatDialog, successBlock: { (response, dialog) in
    dialog.join(completionBlock: { (error) in  
    })
}, errorBlock: { (response) in
    
})
QBChatDialog *chatDialog = [[QBChatDialog alloc] initWithDialogID:nil type:QBChatDialogTypeGroup];
chatDialog.name = @"Group dialog name";
chatDialog.occupantIDs = @[@34, @45, @55];

[QBRequest createDialog:chatDialog successBlock:^(QBResponse * _Nonnull response, QBChatDialog * _Nonnull dialog) {
    [dialog joinWithCompletionBlock:^(NSError * _Nullable error) {
        
    }];
} errorBlock:^(QBResponse * _Nonnull response) {

}];

It's possible to create a public dialog, so any user from your application can be joined to it. There is no list of occupants. This dialog is open for everybody. You need to set the dialog type field to public.

let dialog = QBChatDialog(dialogID: nil, type: .public)
dialog.name = "Public dialog name"
dialog.dialogDescription = "Public dialog description"
// dialog.photo = "...";
    
QBRequest.createDialog(chatDialog, successBlock: { (response, dialog) in
    dialog.join(completionBlock: { (error) in  
    })                                             
}, errorBlock: { (response) in
    
})
QBChatDialog *dialog = [[QBChatDialog alloc] initWithDialogID:nil type:QBChatDialogTypePublicGroup];
dialog.name = @"Public dialog name";
dialog.dialogDescription = @"Public dialog description";
// dialog.photo = @"...";
    
[QBRequest createDialog:chatDialog successBlock:^(QBResponse * _Nonnull response, QBChatDialog * _Nonnull dialog) {
    [dialog joinWithCompletionBlock:^(NSError * _Nullable error) {
        
    }];
} errorBlock:^(QBResponse * _Nonnull response) {

}]

Create dialog with custom parameters

Any dialog can be extended with additional parameters whether it is a private, group, or public. These parameters can be used to store additional data. Also, these parameters can be used in dialogs retrieval request.

To start using additional parameters, create an additional schema of your parameters. This is a Custom Objects class. Just create an empty class with all fields that you need. These fields will be additional parameters in your dialog. See this section to learn how to create a schema using Custom Objects.

Then, specify the parameters defined in the schema in a new dialog.

let chatDialog = QBChatDialog(dialogID: nil, type: .group)
chatDialog.name = "Movies"
chatDialog.occupantIDs = [34, 45, 55]
let customParameters = ["class_name": "Movie", "name": "Star Wars", "rating": 9.1, "documentary": false, "genre": "fantasy", "descriptions": "Star Wars is an American epic space opera."]
chatDialog.data = customParameters

QBRequest.createDialog(chatDialog, successBlock: { (response, dialog) in
    //Block with response and user instances if the request is succeeded.
    dialog.join(completionBlock: { (error) in
    })
}, errorBlock: { (response) in
    //Block with response instance if the request is failed.
})
QBChatDialog *chatDialog = [[QBChatDialog alloc] initWithDialogID:nil type:QBChatDialogTypeGroup];
chatDialog.name = @"Movies";
chatDialog.occupantIDs = @[@34, @45, @55];
NSDictionary<NSString *, id> *customParameters = @{@"class_name": @"Movie", @"name": @"Star Wars", @"rating": @(9.1), @"documentary": @(false), @"genre": @"fantasy", @"descriptions": @"Star Wars is an American epic space opera franchise consisting of a film series created by George Lucas."};
chatDialog.data = customParameters;

[QBRequest createDialog:chatDialog successBlock:^(QBResponse * _Nonnull response, QBChatDialog * _Nonnull dialog) {
    //Block with response and user instances if the request is succeeded.
    [dialog joinWithCompletionBlock:^(NSError * _Nullable error) {
    }];
} errorBlock:^(QBResponse * _Nonnull response) {
    //Block with response instance if the request is failed.
}];

Join dialog

Before you start chatting in a group or public dialog, you need to join it by calling the join() method. If you've successfully joined the dialog, you can send/receive messages in real-time. See this section to learn how to send/receive messages.

let groupDialog = ...
groupDialog.join { (error) in
    
}
QBChatDialog *groupDialog = ...;
[groupDialog joinWithCompletionBlock:^(NSError * _Nullable error) {
    
}];

Let's see, how the join() method is used with regard to the dialog type.

Capabilities

Public

Group

Private

Join

📘

You can join a group dialog only if your user ID is present in the occupantIDs array, in the dialog model.

Your user ID is added to the occupantIDs array if you create a dialog or you are added to the dialog by the other user. See this section to learn how to add/remove occupants from the group dialog.

Leave dialog

You can leave the group and public dialog by calling the leave() method. If the dialog is left, you can't send/receive messages. To be able to receive/send messages, you need to join it.

let groupDialog = ...
groupDialog.leave { (error) in
    
}
QBChatDialog *groupDialog = ...;
[groupDialog leaveWithCompletionBlock:^(NSError * _Nullable error) {
    
}];

Let's see, how the leave() method is used with regard to the dialog type.

Capabilities

Public

Group

Private

Leave

📘

When a group dialog is left, your user ID is still present in the occupantIDs array, in the dialog model. As a result, the dialog will still be present in the list of dialogs and you will still have access to the chat history.

To remove yourself from the group dialog, use the update() method. See this section to learn how to remove occupants from the group dialog.

Retrieve list of dialogs

It's common to request all your dialogs on every app login. The request below will return all private, group, and public dialogs you participate in.

QBRequest.dialogs(for: QBResponsePage(limit: 50, skip: 100), extendedRequest: nil, successBlock: { (response, dialogs, dialogsUsersIDs, page) in

}, errorBlock: { (response) in
    
})
[QBRequest dialogsForPage:[QBResponsePage responsePageWithLimit:50 skip:100] extendedRequest:nil successBlock:^( response, dialogs, dialogsUsersIDs, page) {
        
} errorBlock:^(QBResponse * _Nonnull response) {
       
}];

Filters

If you want to retrieve only dialogs updated after some specific date time, you can pass the filter. This is useful if you cache dialogs somehow and do not want to obtain the whole list of your dialogs on every app start.

You can apply filters for the following fields:

  • _id (string)
  • type (integer)
  • name (string)
  • last_message_date_sent (integer)
  • created_at (date)
  • updated_at (date)

You can apply sort for the following fields:

  • last_message_date_sent

Filter

Applicable to types

Description

{field_name}

All types

Search records with the field which contains the specified value.

{field_name}[{search_operator}]

All types

Search a record with the field which contains the value according to the specified value and operator.

sort_asc

All types

Search results will be sorted by the specified field in ascending order.

sort_desc

All types

Search results will be sorted by the specified field in descending order.

skip

Integer

Skip N records in search results. Useful for pagination. Default (if not specified): 0.

limit

Integer

Limit search results to N records. Useful for pagination. Default value: 100. If limit is equal to 1, only the last record will be returned.

count

Integer

Count search results. Response will contain only count of records found.

Search operators

Here are the search operators that you can use to retrieve dialogs.

Search operators

Applicable to types

Description

lt

Integer, Float

Less Than operator.

lte

Integer, Float

Less Than or Equal to operator.

gt

Integer, Float

Greater Than operator.

gte

Integer, Float

Greater Than or Equal to operator.

ne

Integer, Float, String, Boolean

Not Equal to operator.

in

Integer, Float, String

IN array operator.

nin

Integer, Float, String

Not IN array operator.

all

Array

ALL are contained in array.

ctn

String

All records that contain a particular substring.

Update dialog

You can update the information for a private, group, and public dialog.

chatDialog.name = "New dialog name"
chatDialog.dialogDescription = "New dialog description"
chatDialog.photo = "https://new_photo_url" // or it can be an ID to some file in Storage module
    
QBRequest.update(chatDialog, successBlock: { (response, updatedDialog) in

}, errorBlock: { (response) in
    
})
dialog.name = @"New dialog name";
dialog.dialogDescription = @"New dialog description";
dialog.photo = @"https://new_photo_url"; // or it can be an ID to some file in Storage module

[QBRequest updateDialog:dialog successBlock:^(QBResponse * _Nonnull response, QBChatDialog * _Nonnull updatedDialog) {

} errorBlock:^(QBResponse * _Nonnull response) {

}];

Let's see what capabilities a particular user role has with regard to the dialog type.

Capabilities

Public dialog

Group dialog

Private dialog

Update a dialog name

Owner

Owner

Update a photo

Owner

Owner

Update custom parameters

Owner

Owner

Owner
Occupant

Add/Remove occupants

You can add/remove occupants in a group dialog. Set pushOccupantsIDs filed to add occupants to the dialog. Set the pullOccupantsIDs field to remove occupants from the dialog. As a result, the user ID will be added to the oppupantIDs array or removed from it.

let pushOccupantsIDs = [10056, 75432].map({ $0.stringValue })
chatDialog.pushOccupantsIDs = pushOccupantsIDs
QBRequest.update(chatDialog, successBlock: { (response, updatedDialog) in

}, errorBlock: { (response) in
    
})
dialog.pushOccupantsIDs = @[@"10056", @"75432"];
[QBRequest updateDialog:dialog successBlock:^(QBResponse * _Nonnull response, QBChatDialog * _Nonnull updatedDialog) {

} errorBlock:^(QBResponse * _Nonnull response) {

}];

Let's see what capabilities a particular user role has with regard to the dialog type.

Capabilities

Public dialog

Group dialog

Private dialog

Add other users

Owner
Occupant

Remove other users

Owner
Occupant

Remove yourself

Owner
Occupant

Delete dialog

A request below will remove a dialog for a current user, but other users will be still able to chat there.

QBRequest.deleteDialogs(withIDs: Set<String>(["5356c64ab35c12bd3b108a41", "d256c64ab35c12bd3b108bc5"]), forAllUsers: false, successBlock: { (deletedObjectsIDs, notFoundObjectsIDs, wrongPermissionsObjectsIDs) in
    
}, errorBlock: { (response) in
    
})
[QBRequest deleteDialogsWithIDs:[NSSet setWithArray:@[@"5356c64ab35c12bd3b108a41", @"d256c64ab35c12bd3b108bc5"]] forAllUsers:NO successBlock:^( deletedObjectsIDs, notFoundObjectsIDs, wrongPermissionsObjectsIDs) {
    
} errorBlock:^(QBResponse * _Nonnull response) {

}];

Set the forAllUsers parameter as true to completely remove the dialog for all users. You can also delete multiple dialogs in a single request.

Let's see what capabilities a particular user role has with regard to the dialog type.

Capabilities

Public

Group

Private

Delete a dialog for all users
using the forAllUsers
parameter

Owner

Owner

Owner
Occupant

Delete a dialog for a current user

Owner

Owner

Owner
Occupant

Get number of unread messages

To get a number of unread messages from a particular dialog, use the code snippet below.

let unreadMessagesCount = dialog.unreadMessagesCount
NSUInteger unreadMessagesCount = chatDialog.unreadMessagesCount;

You can also retrieve the total number of unread messages using the totalUnreadMessageCountForDialogs() method . It returns the total count of unread messages for all dialogs of the user in totalUnreadCount. It also returns unread messages count for dialogs with IDs in dialogsDictionary if any dialogIDs are specified.

let dialogIDs: Set<String> = ["8b23aa4f5d0b0be0900041aa", "1c23aa4f5d0b0be0900041ad"]
QBRequest.totalUnreadMessageCountForDialogs(withIDs: dialogIDs, successBlock: { ( response, totalUnreadCount, dialogsDictionary) in
    
}, errorBlock: { (response) in
    
})
[QBRequest totalUnreadMessageCountForDialogsWithIDs:[NSSet setWithArray:@[@"8b23aa4f5d0b0be0900041aa", @"1c23aa4f5d0b0be0900041ad"]]
successBlock:^(QBResponse * _Nonnull response, NSUInteger count, NSDictionary<NSString *,id> * _Nonnull dialogs) {
    
} errorBlock:^(QBResponse * _Nonnull response) {
    
}];

Argument

Required

Description

dialogIDs

yes

IDs of dialogs.

  • If dialogIDs are not specified, the total number of unread messages for all dialogs of the user will be returned.
  • If dialogIDs are specified, the number of unread messages for each specified dialog will be returned. Also, the total number of unread messages for all dialogs of the user will be returned.

Updated 10 days ago


What's Next

Messaging

Dialogs


Suggested Edits are limited on API Reference Pages

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