Before you begin
- Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.
- 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.
- Configure QuickBlox SDK for your app. Check out our Setup page for more details.
- Create a user session to be able to use QuickBlox functionality. See our Authentication page to learn how to do it.
- 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 QBChatDialogTypes.CHAT
dialog type and ID of an opponent you want to create a chat with.
try {
QBDialog createdDialog = await QB.chat.createDialog(
[234234324, 3243243],
"Private Chat",
dialogType: QBChatDialogTypes.CHAT);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Argument | Required | Description |
---|---|---|
occupantIds | yes | IDs of opponents. |
dialogName | yes | The name of the dialog. |
dialogType | no | A type of a dialog. By default, a public dialog will be created. |
To create a group dialog for a predefined number of occupants, you need to set the QBChatDialogTypes.GROUP_CHAT
dialog type and IDs of opponents you want to create a chat with.
try {
QBDialog createdDialog = await QB.chat.createDialog(
[234234324, 3243243],
"Group Chat",
dialogType: QBChatDialogTypes.GROUP_CHAT);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Argument | Required | Description |
---|---|---|
occupantIds | yes | A list of opponents. |
dialogName | yes | The name of the dialog. |
dialogType | no | A type of the dialog. By default, the public dialog will be created. |
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 QBChatDialogTypes.PUBLIC_CHAT
dialog type to create a public dialog.
try {
QBDialog createdDialog = await QB.chat.createDialog(
[234234324, 3243243],
"Public Chat",
dialogType: QBChatDialogTypes.PUBLIC_CHAT);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Argument | Required | Description |
---|---|---|
occupantIds | yes | A list of opponents. |
dialogName | yes | The name of the dialog. |
dialogType | no | A type of the dialog. By default, the public dialog will be created. |
Join dialog
Before you start chatting in a group or public dialog, you need to join it by calling the joinDialog()
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.
try {
await QB.chat.joinDialog(dialogId);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Let's see, how the joinDialog()
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 leaveDialog()
method. If the dialog is left, you can't send/receive messages. To be able to receive/send messages, you need to join it.
try {
await QB.chat.leaveDialog(dialogId);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Capabilities | Public | Group | Private |
---|---|---|---|
Leave | ✓ | ✓ | ✗ |
When a group dialog is left, your user ID is removed
occupantIDs
array, in the dialog model. As a result, the dialog is removed from the list of dialogs and you won't have access to the chat history.To remove a dialog for all users, use the
deleteDialog()
method. See this section to learn how to delete the dialog completely for all users.
Retrieve list of dialogs
It's common to request all your dialogs on every app login. The request below will return all your private, group, and public dialogs you participate in.
try {
List<QBDialog> dialogs = await QB.chat.getDialogs(
sort: qbSort,
filter: qbFilter,
limit: limit,
skip: skip);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Argument | Required | Description |
---|---|---|
sort | no | A parameter for sorting dialogs. |
filter | no | A parameter for filtering dialogs. |
limit | no | A limit load dialog quantity. |
skip | no | A quantity of skipped dialogs. |
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.
try {
QBDialog updatedDialog = await QB.chat.updateDialog(
dialogId,
dialogName: dialogName);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
Argument | Required | Description |
---|---|---|
dialogId | yes | The ID of the dialog. |
addUsers | no | A list of users that will be added. |
removeUser | no | A list of users that will be removed. |
dialogName | no | A name of the dialog. |
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 | ✗ |
Add/Remove occupant
You can add/remove occupants in a group dialog. Set the addUsers
parameter to add occupants to the dialog. Set the removeUsers
parameter to remove occupants from the dialog. As a result, the ID of the opponent will be added to the oppupantIDs
array or removed from it.
try {
QBDialog updatedDialog = await QB.chat.updateDialog(
dialogId,
addUsers: addUsers,
removeUsers: removeUsers);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
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 | ✗ |
Remove other users | ✗ | Owner | ✗ |
Remove yourself | ✗ | Owner | ✗ |
Delete dialog
Delete a dialog for all users using the request below. When deleting a group dialog, all user IDs will be removed from the oppupantIDs
array in the dialog model. You can also delete multiple dialogs in a single request.
To delete a dialog for yourself, just leave the dialog. See this section for more information.
try {
await QB.chat.deleteDialog(dialogId);
} on PlatformException catch (e) {
// Some error occured, look at the exception message for more details
}
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 | Owner | Owner | Owner |
Updated 10 days ago
What's Next
Messaging |