Before you begin
- 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 Setup page for more details.
- Create a user session to be able to use QuickBlox functionality. See Authentication page to learn how to do it.
- Connect to the Chat server. See 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.
Create dialog
To create a private dialog, you need to set the dialog type toQBDialogType.PRIVATE
and ID of an opponent you want to create a chat with.
QBDialogType.GROUP
and IDs of opponents you want to create a chat with using the QBChatDialog
value.
QBDialogType.PUBLIC_GROUP
as a dialog type.
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 requests. 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.Join dialog
Before you start chatting in a group or public dialog, you need to join it by calling thejoin()
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.
XMPPException
and SmackException
. But in case of using .performAsync()
, you will receive onSuccess()
or onError()
callbacks.
To define if you have already joined the dialog, you should call the appropriate method from the dialog model.
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 occupants to the group dialog.Leave dialog
You can leave the group and public dialog by calling theleave()
method. If the dialog is left, you can’t send/receive messages. To be able to receive/send messages, you need to join it.
leave()
method is used with regard to the dialog type.
Capabilities | Public | Group | Private |
---|---|---|---|
Leave | ✓ | ✓ | ✗ |
When you leave a group dialog, 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 updateChatDialog()
method. See this section to learn how to remove occupants from the group dialog.Retrieve online users
You can get a list of dialog occupants who are currently online. Call therequestOnlineUsers()
method to get the list of online users who are joined to the dialog. As a result, a list of user IDs is returned.
requestOnlineUsers()
method is used with regard to the dialog type
Capabilities | Public | Group | Private |
---|---|---|---|
Retrieve online users | ✗ | ✓ | ✗ |
You can retrieve online users from the group dialog only if you are joined to it.
Retrieve list of dialogs
It’s common to request all your dialogs on every app login. The request below will return group dialogs containing thetest
in the names, sorted in descending order, and limited to 50 dialogs on the page.
Argument | Required | Description |
---|---|---|
type | yes | Dialog type. Pass null to retrieve all dialogs. |
requestBuilder | yes | Allows to set parameters for the request. |
QBRequestGetBuilder
class.
If you want to get a paginated list of users from the server, you can set the following pagination parameters in the QBRequestGetBuilder
class.
Pagination parameter | Description |
---|---|
skip | Skip N records in search results. Useful for pagination. Default (if not specified): 0. |
limit | Limit search results to N records. Useful for pagination. Default value: 100. |
Search operators
You can use search operators to get more specific search results. The request below will return group dialogs in the array containingtest
in their names.
Methods | Applicable to types | Applicable to fields | Description |
---|---|---|---|
lt(field, searchValue) | number, string, date | last_message_date_sent, created_at, updated_at | Less Than operator. |
lte(field, searchValue) | number, string, date | last_message_date_sent, created_at, updated_at | Less Than or Equal to operator. |
gt(field, searchValue) | number, string, date | last_message_date_sent, created_at, updated_at | Greater Than operator. |
gte(field, searchValue) | number, string, date | last_message_date_sent, created_at, updated_at | Greater Than or Equal to operator. |
ne(field, searchValue) | number, string, date | _id, name, last_message_date_sent | Not Equal to operator. |
in(field, searchValue) | number, string, date | type, last_message_date_sent, name | IN array operator. |
nin(field, searchValue) | number, string, date | last_message_date_sent | Not IN array operator. |
all(field, searchValue) | number | occupants_ids | ALL are contained in array. |
ctn(field, searchValue) | string | name | All records that contain a particular substring. |
Sort operators
You can use sort operators to order the search results. The request below will return group dialogs by the field sorted in descending order.Methods | Applicable to types | Applicable to fields | Description |
---|---|---|---|
sortAsc(field) | All types | id, created_at, name, last_message_date_sent | Search results will be sorted in ascending order by the specified field. |
sortDesc(field) | All types | id, created_at, name, last_message_date_sent | Search results will be sorted in descending order by the specified field. |
Update dialog
You can update the information for a private, group, and public dialog.Capabilities | Public dialog | Group dialog | Private dialog |
---|---|---|---|
Update a dialog name | Owner | Owner | ✗ |
Update a photo | Owner | Owner | ✗ |
Update custom parameters | Owner,Occupant | Owner,Occupant | Owner,Occupant |
Add occupants
You can add occupants in a group dialog by using theaddUsers()
method. As a result, your ID will be added to the occupantIDs
array.
Argument | Required | Description |
---|---|---|
dialog | yes | A dialog to add users to. |
requestBuilder | yes | Specifies requestBuilder fields that should be set. |
Capabilities | Public dialog | Group dialog | Private dialog |
---|---|---|---|
Add other users | ✗ | Owner,Occupant | ✗ |
Remove occupants
You can remove occupants from a group dialog by using theremoveUsers()
method. As a result, the IDs will be removed the occupantIDs
array.
Argument | Required | Description |
---|---|---|
dialog | yes | A dialog to remove users from. |
requestBuilder | yes | Specifies requestBuilder fields that should be set. |
Capabilities | Public dialog | Group dialog | Private dialog |
---|---|---|---|
Remove other users | ✗ | Owner | ✗ |
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.forceDelete
parameter as true
to completely remove the dialog for all users. You can also delete multiple dialogs in a single request.
You can also use multiple dialogs deleting using the snippet below.
Capabilities | Public | Group | Private |
---|---|---|---|
Delete a dialog for all usersusing the forceDeleteparameter. | Owner | Owner | Owner |
Delete a dialog for a current user | Owner | Owner,Occupant | Owner,Occupant |
Get number of dialogs
You can get a number of dialogs using thegetChatDialogsCount()
method. The request below will return a count of all group dialogs.
Argument | Required | Description |
---|---|---|
requestBuilder | yes | Allows to set parameters for the request. |
bundle | no | The bundle with response additional information. |
Get number of unread messages
To get a number of unread messages from a particular dialog, use the code snippet below.getTotalUnreadMessagesCount()
method.
Argument | Required | Description |
---|---|---|
dialogsIds | yes | IDs of dialogs.- If dialogsIds are not specified, the total number of unread messages for all dialogs of the user will be returned.- If dialogsIds 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. |
Resources
A sequence of steps a user takes to start a dialog by moving through the application lifecycle.