Dialogs

​

Before you begin

1. 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.
2. Configure QuickBlox SDK for your app. Check out our Setup page for more details.
3. Create a user session to be able to use QuickBlox functionality. See our Authentication page to learn how to do it.
4. Connect to the Chat server. See our Connection page to learn how to do it.

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

​

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

})

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]
// Photo can be a link to a file in Content module, Custom Objects module or just a web link.
// dialog.photo = "...";

QBRequest.createDialog(chatDialog, successBlock: { (response, dialog) in
    dialog.join(completionBlock: { (error) in
    })
}, errorBlock: { (response) in

})

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"
// Photo can be a link to a file in Content module, Custom Objects module or just a web link.
// dialog.photo = "...";

QBRequest.createDialog(chatDialog, successBlock: { (response, dialog) in
    dialog.join(completionBlock: { (error) in
    })
}, errorBlock: { (response) in

})

​

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.
})

​

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

}

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

To subscribe to the onJoinOccupant event, use the code snippet below. As a result, you will be notified by the SDK about the onJoinOccupant() event whenever the occupant has joined the current group dialog.

chatDialog.onJoinOccupant = { (userID) in

}

​

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.

SwiftObjective-

let groupDialog = ...
groupDialog.leave { (error) in

}

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

To subscribe to the onLeaveOccupant event, use the code snippet below. As a result, you will be notified by the SDK about the onLeaveOccupant() event whenever the occupant has left the current group dialog.

chatDialog.onLeaveOccupant = { (userID) in

}

​

Retrieve online users

You can get a list of online users from the chatDialog dialog. Call the requestOnlineUsers() method to get the list of online users who are joined to the dialog. As a result, a completion block with an array of user IDs or failure error is called.

chatDialog.requestOnlineUsers { (onlineUsersIDs, error) in

}

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

​

Retrieve list of dialogs

It’s common to request all your dialogs on every app login. The request below will return private, group, and public dialogs that have been updated during the last month, sorted by the last_message_date_sent in descending order, and limited to 10 dialogs per page.

//get dialogs that have been updated during the last month and sort by the date of the last message in descending order
let monthAgoDate = Calendar.current.date( byAdding: .month, value: -1, to: Date())
let timeInterval = monthAgoDate!.timeIntervalSince1970

let paramSort = "sort_desc"
let sortValue = "last_message_date_sent"
let paramFilter = "updated_at[gte]"
let filterValue = "\(timeInterval)"

var extendedRequest: [String: String] = [:]
extendedRequest[paramSort] = sortValue
extendedRequest[paramFilter] = filterValue
let responsePage = QBResponsePage(limit: 10)

QBRequest.dialogs(for: responsePage, extendedRequest: extendedRequest, successBlock: { response, dialogs, dialogsUsersIDs, page in

}, errorBlock: { response in

})

If you want to retrieve only dialogs updated after some specific date time and order the search results, you can apply operators. This is useful if you cache dialogs somehow and do not want to obtain the whole list of dialogs on every app start. Thus, you can apply search and sort operators to list dialogs on the page so that it is easier to view specific dialogs. The operators are set as key-value parameters in the extendedRequest dictionary.

​

Search operators

You can use search operators to get more specific search results. The request below will return 10 dialogs that were updated over the last month.

//get dialogs that have been updated over the last month
let monthAgoDate = Calendar.current.date( byAdding: .month, value: -1, to: Date())
let timeInterval = monthAgoDate!.timeIntervalSince1970

let paramFilter = "updated_at[gte]"
let filterValue = "\(timeInterval)"

var extendedRequest: [String: String] = [:]
extendedRequest[paramFilter] = filterValue
let responsePage = QBResponsePage(limit: 10)

QBRequest.dialogs(for: responsePage, extendedRequest: extendedRequest, successBlock: { response, dialogs, dialogsUsersIDs, page in

}, errorBlock: { response in

})

Here are the search operators that you can use to search for the exact data that you need.

​

Sort operators

You can use sort operators to order the search results. The request below will return dialogs sorted in descending order by the last_message_date_sent field.

let paramSort = "sort_desc"
let sortValue = "last_message_date_sent"

var extendedRequest: [String: String] = [:]
extendedRequest[paramSort] = sortValue
let responsePage = QBResponsePage(limit: 10)

QBRequest.dialogs(for: responsePage, extendedRequest: extendedRequest, successBlock: { response, dialogs, dialogsUsersIDs, page in

}, errorBlock: { response in

})

Here are the sort operators that you can use to order the search results:

​

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

})

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

​

Add occupants

Set pushOccupantsIDs field to add occupants to the group dialog. As a result, the user ID will be added to the occupantIDs array.

chatDialog.pushOccupantsIDs = ["10056", "75432"]
QBRequest.update(chatDialog, successBlock: { (response, updatedDialog) in

}, errorBlock: { (response) in

})

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

​

Remove occupants

Set the pullOccupantsIDs field to remove occupants from the group dialog. As a result, the user ID will be removed from the occupantIDs array.

chatDialog.pullOccupantsIDs = ["10056", "75432"]
QBRequest.update(chatDialog, successBlock: { (response, updatedDialog) in

}, errorBlock: { (response) in

})

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

​

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

})

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.

​

Get number of dialogs

You can get a number of dialogs using the countOfDialogs(withExtendedRequest:) method. The request below will return a count of dialogs updated over the last month.

//get dialogs that have been updated during the last month and sort by the date of the last message in descending order
let monthAgoDate = Calendar.current.date( byAdding: .month, value: -1, to: Date())
let timeInterval = monthAgoDate!.timeIntervalSince1970

let paramFilter = "updated_at[gte]"
let filterValue = "\(timeInterval)"

var extendedRequest: [String: String] = [:]
extendedRequest[paramFilter] = filterValue

QBRequest.countOfDialogs(withExtendedRequest: extendedRequest, successBlock: { response, count in

}, errorBlock: { response in

})

​

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

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

})

​

Resources

A sequence of steps a user takes to start a dialog by moving through the application lifecycle.