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.

Dialogs

Learn how to create and manage 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 to QBDialogType.PRIVATE and ID of an opponent you want to create a chat with.

ArrayList<Integer> occupantIdsList = new ArrayList<Integer>();
occupantIdsList.add(123);
 
QBChatDialog dialog = new QBChatDialog();
dialog.setType(QBDialogType.PRIVATE);
dialog.setOccupantsIds(occupantIdsList);
 
// or just use DialogUtils
//QBChatDialog dialog = DialogUtils.buildPrivateDialog(recipientId);
 
QBRestChatService.createChatDialog(dialog).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog result, Bundle params) {
 
    }
 
    @Override
    public void onError(QBResponseException responseException) {
 
    }
});
val occupantIdsList = ArrayList<Int>()
occupantIdsList.add(123)

val dialog = QBChatDialog()
dialog.type = QBDialogType.PRIVATE
dialog.setOccupantsIds(occupantIdsList)

// or just use DialogUtils
//QBChatDialog dialog = DialogUtils.buildPrivateDialog(recipientId);

QBRestChatService.createChatDialog(dialog).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(result: QBChatDialog?, params: Bundle?) {

    }

    override fun onError(responseException: QBResponseException?) {

    }
})

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

ArrayList<Integer> occupantIdsList = new ArrayList<Integer>();
occupantIdsList.add(123);
occupantIdsList.add(234);
occupantIdsList.add(345);
occupantIdsList.add(456);

QBChatDialog dialog = new QBChatDialog();
dialog.setName("Group chat");
dialog.setType(QBDialogType.GROUP);
dialog.setOccupantsIds(occupantIdsList);

// or just use DialogUtils
// QBChatDialog dialog = DialogUtils.buildDialog("Chat with Friends", QBDialogType.GROUP, occupantIdsList);

QBRestChatService.createChatDialog(dialog).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog result, Bundle params) {

    }

    @Override
    public void onError(QBResponseException responseException) {

    }
});
val occupantIdsList = ArrayList<Int>()
occupantIdsList.add(123)
occupantIdsList.add(234)
occupantIdsList.add(345)
occupantIdsList.add(456)

val dialog = QBChatDialog()
dialog.name = "Group chat"
dialog.type = QBDialogType.GROUP
dialog.setOccupantsIds(occupantIdsList)

// or just use DialogUtils
// QBChatDialog dialog = DialogUtils.buildDialog("Chat with Friends", QBDialogType.GROUP, occupantIdsList);

QBRestChatService.createChatDialog(dialog).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(result: QBChatDialog?, params: Bundle?) {

    }

    override fun onError(responseException: QBResponseException?) {

    }
})

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 just need to set QBDialogType.PUBLIC_GROUP as a dialog type.

QBChatDialog dialog = new QBChatDialog();
dialog.setName("Public group chat");
dialog.setType(QBDialogType.PUBLIC_GROUP);

QBRestChatService.createChatDialog(dialog).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog result, Bundle params) {

    }

    @Override
    public void onError(QBResponseException responseException) {

    }
});
val dialog = QBChatDialog()
dialog.name = "Public group chat"
dialog.type = QBDialogType.PUBLIC_GROUP

QBRestChatService.createChatDialog(dialog).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(result: QBChatDialog?, params: Bundle?) {

    }

    override fun onError(responseException: QBResponseException?) {

    }
})

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.

private void createDialogWithCurtomParameters() {
    QBDialogCustomData customData = new QBDialogCustomData();
    customData.putBoolean("customBoolean", true);
    customData.putInteger("customInteger", 327);
    customData.putString("customString", "Value");
    customData.putDate("customDate", new Date());
    customData.putFloat("customFloat", 327.2f);
    List<String> paramsList = new ArrayList<>();
    paramsList.add("param1");
    customData.putArray("nameOfCustomArray", paramsList);

    QBChatDialog qbChatDialog = new QBChatDialog();
    qbChatDialog.setCustomData(customData);

    QBRestChatService.createChatDialog(qbChatDialog).performAsync(new QBEntityCallback<QBChatDialog>() {
        @Override
        public void onSuccess(QBChatDialog qbChatDialog, Bundle bundle) {

        }

        @Override
        public void onError(QBResponseException e) {

        }
    });
}

// now we can get the same parameters from any dialog we load
private void getDataFromDialog(QBChatDialog qbChatDialog) {
    Integer customInteger = qbChatDialog.getCustomData().getInteger("customInteger");
    String customString = qbChatDialog.getCustomData().getString("customString");
    }
private fun createDialogWithCustomParameters() {
    val customData = QBDialogCustomData()
    customData.putBoolean("customBoolean", true)
    customData.putInteger("customInteger", 327)
    customData.putString("customString", "Value")
    customData.putDate("customDate", Date())
    customData.putFloat("customFloat", 327.2f)
    val paramsList = ArrayList<String>()
    paramsList.add("param1")
    customData.putArray("nameOfCustomArray", paramsList)

    val qbChatDialog = QBChatDialog()
    qbChatDialog.customData = customData

    QBRestChatService.createChatDialog(qbChatDialog).performAsync(object : QBEntityCallback<QBChatDialog> {
        override fun onSuccess(qbChatDialog: QBChatDialog?, bundle: Bundle?) {

        }

        override fun onError(e: QBResponseException?) {

        }
    })
}

// Now we can get the same parameters from any dialog we load
private fun getDataFromDialog(qbChatDialog: QBChatDialog) {
    val customInteger = qbChatDialog.customData.getInteger("customInteger")
    val customString = qbChatDialog.customData.getString("customString")
}

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.

for (QBChatDialog dialog : qbChatDialogs) {
    if (dialog.getType() != QBDialogType.PRIVATE) {
        try {
            dialog.join(new DiscussionHistory());
        } catch (XMPPException e) {

        } catch (SmackException e) {

        }
    }
}
for (dialog in qbChatDialogs) {
    if (dialog.type != QBDialogType.PRIVATE) {
        try {
            dialog.join(DiscussionHistory())
        } catch (e: XMPPException) {

        } catch (e: SmackException) {

        }
    }
 }

This is a synchronous way to join dialogs, so you need to handle 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.

anyDialog.isJoined();
anyDialog.isJoined()

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 occupants to 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.

try {
    groupDialog.leave();
} catch (XMPPException | SmackException.NotConnectedException e) {

}
try {
    groupDialog.leave()
} catch (e: XMPPException) {

} catch (e: SmackException.NotConnectedException) {

}

Let's see, how the 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 the requestOnlineUsers() method to get the list of online users who are joined to the dialog. As a result, a list of user IDs is returned.

try {
    Collection<Integer> onlineUsersIds = qbChatDialog.requestOnlineUsers();
} catch (XMPPException.XMPPErrorException e) {

} catch (SmackException.NotConnectedException e) {

} catch (SmackException.NoResponseException e) {

}
try {
    val onlineUsersIds = qbChatDialog.requestOnlineUsers()
} catch (e: XMPPErrorException) {
   
} catch (e: NotConnectedException) {
    
} catch (e: NoResponseException) {
   
}

Let's see, how the 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 all private, group, and public dialogs you participate in.

QBRequestGetBuilder requestBuilder = new QBRequestGetBuilder();
requestBuilder.setLimit(50);
//requestBuilder.setSkip(100);
//requestBuilder.sortAsc("last_message_date_sent");

QBRestChatService.getChatDialogs(null, requestBuilder).performAsync(new QBEntityCallback<ArrayList<QBChatDialog>>() {
    @Override
    public void onSuccess(ArrayList<QBChatDialog> result, Bundle params) {
      
    }

    @Override
    public void onError(QBResponseException responseException) {

    }
});
val requestBuilder = QBRequestGetBuilder()
requestBuilder.limit = 50
//requestBuilder.setSkip(100);
//requestBuilder.sortAsc("last_message_date_sent");

QBRestChatService.getChatDialogs(null, requestBuilder).performAsync(object : QBEntityCallback<ArrayList<QBChatDialog>> {
    override fun onSuccess(result: ArrayList<QBChatDialog>?, params: Bundle?) {
      
    }

    override fun onError(responseException: QBResponseException?) {

    }
})

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.

QBChatDialog dialog = new QBChatDialog();
dialog.setDialogId("dsfsd934329hjhkda98793j2");  // To make updates - the dialog must contain dialogId
dialog.setName("Team room");
dialog.setPhoto("https://new_photo_url"); // or it can be ID of uploaded File with QBContent

QBRequestUpdateBuilder requestBuilder = new QBRequestUpdateBuilder();

QBRestChatService.updateChatDialog(dialog, requestBuilder).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog updatedDialog, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});
val dialog = QBChatDialog()
dialog.dialogId = "dsfsd934329hjhkda98793j2"  // To make updates - the dialog must contain dialogId
dialog.name = "Team room"
dialog.photo = "https://new_photo_url" // or it can be ID of uploaded File with QBContent

val requestBuilder = QBRequestUpdateBuilder()

QBRestChatService.updateChatDialog(dialog, requestBuilder).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(updatedDialog: QBChatDialog?, bundle: Bundle?) {

    }

    override fun onError(e: QBResponseException?) {

    }
})

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,
Occupant

Owner,
Occupant

Owner,
Occupant

Add occupants

You can add occupants in a group dialog by using the addUsers() method. As a result, your ID will be added to the occupantIDs array.

// To add users you should pass whole QBUser model or it's ID (user.getId)
QBDialogRequestBuilder requestBuilder = new QBDialogRequestBuilder();

QBChatDialog dialog = new QBChatDialog();

ArrayList<QBUser> usersToAdd = new ArrayList<QBUser>();
usersToAdd.add(QBUser());
usersToAdd.add(QBUser());

QBUser[] usersArray = new QBUser[usersToAdd.size()];
qbRequestBuilder.addUsers(usersToAdd.toArray(usersArray));

QBRestChatService.updateChatDialog(dialog, requestBuilder).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog chatDialog, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});
// To add users you should pass whole QBUser model or it's ID (user.getId)
val requestBuilder = QBDialogRequestBuilder()
  
val dialog = QBChatDialog()
  
val usersToAdd = ArrayList<QBUser>()
usersToAdd.add(QBUser())
usersToAdd.add(QBUser())
  
qbRequestBuilder.addUsers(*usersToAdd.toTypedArray())
  
QBRestChatService.updateChatDialog(dialog, requestBuilder).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(qbChatDialog: QBChatDialog?, bundle: Bundle?) {
      
    }
  
    override fun onError(e: QBResponseException?) {
      
    }
})

Argument

Required

Description

dialog

yes

A dialog to add users to.

requestBuilder

yes

Specifies requestBuilder fields that should be set.

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 occupants

You can remove occupants from a group dialog by using the removeUsers() method. As a result, the IDs will be removed the occupantIDs array.

// To remove users you should pass whole QBUser model or it's ID (user.getId)
QBDialogRequestBuilder requestBuilder = new QBDialogRequestBuilder();

QBChatDialog dialog = new QBChatDialog();

ArrayList<QBUser> usersToRemove = new ArrayList<QBUser>();
usersToRemove.add(QBUser());
usersToRemove.add(QBUser());

QBUser[] usersArray = new QBUser[usersToRemove.size()];
qbRequestBuilder.removeUsers(usersToRemove.toArray(usersArray));

QBRestChatService.updateChatDialog(dialog, requestBuilder).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog qbChatDialog, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});
// To remove users you should pass whole QBUser model or it's ID (user.getId)
val requestBuilder = QBDialogRequestBuilder()

val dialog = QBChatDialog()
  
val usersToRemove = ArrayList<QBUser>()
usersToRemove.add(QBUser())
usersToRemove.add(QBUser())
  
qbRequestBuilder.removeUsers(*usersToRemove.toTypedArray())

QBRestChatService.updateChatDialog(dialog, requestBuilder).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(qbChatDialog: QBChatDialog?, bundle: Bundle?) {

    }

    override fun onError(e: QBResponseException?) {

    }
})

Argument

Required

Description

dialog

yes

A dialog to remove users from.

requestBuilder

yes

Specifies requestBuilder fields that should be set.

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

Capabilities

Public dialog

Group dialog

Private dialog

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.

String dialogId = qbChatDialog.getDialogId();
boolean forceDelete = false;

QBRestChatService.deleteDialog(dialogId, forceDelete).performAsync(new QBEntityCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});
val dialogId = qbChatDialog.dialogId
val forceDelete = false

QBRestChatService.deleteDialog(dialogId, forceDelete).performAsync(object : QBEntityCallback<Void> {
    override fun onSuccess(aVoid: Void?, bundle: Bundle?) {

    }

    override fun onError(e: QBResponseException?) {

    }
})

Set the 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.

StringifyArrayList<String> qbDialogsIDs = new StringifyArrayList<>();
for (QBChatDialog dialog : qbChatDialogs) {
    qbDialogsIDs.add(dialog.getDialogId());
}

boolean forceDelete = false;

QBRestChatService.deleteDialogs(qbDialogsIDs, forceDelete, null).performAsync(new QBEntityCallback<ArrayList<String>>() {
    @Override
    public void onSuccess(ArrayList<String> strings, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});
val qbDialogsIDs = StringifyArrayList<String>()
for (dialog in qbChatDialogs) {
    qbDialogsIDs.add(dialog.dialogId)
}

val forceDelete = false

QBRestChatService.deleteDialogs(qbDialogsIDs, forceDelete, null).performAsync(object : QBEntityCallback<ArrayList<String>> {
    override fun onSuccess(strings: ArrayList<String>?, bundle: Bundle?) {

    }

    override fun onError(e: QBResponseException?) {

    }
})

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 forceDelete
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.

QBRestChatService.getChatDialogById(dialog.getDialogId()).performAsync(new QBEntityCallback<QBChatDialog>() {
    @Override
    public void onSuccess(QBChatDialog qbChatDialog, Bundle bundle) {
        // get unread messages count
        int unreadMessageCount = qbChatDialog.getUnreadMessageCount();
    }

    @Override
    public void onError(QBResponseException e) {

    }
});
QBRestChatService.getChatDialogById(dialog.dialogId).performAsync(object : QBEntityCallback<QBChatDialog> {
    override fun onSuccess(qbChatDialog: QBChatDialog?, bundle: Bundle?) {
        let unreadMessageCount = qbChatDialog.unreadMessageCount
    }

    override fun onError(e: QBResponseException?) {

    }
})

You can also retrieve total unread messages count by using the getTotalUnreadMessagesCount() method.

Set<String> dialogsIds = new HashSet<String>();
dialogsIds.add("44g9867978v894365tf7g3y4");
dialogsIds.add("47r8738478394ffdi39id493");

QBRestChatService.getTotalUnreadMessagesCount(dialogsIds, null).performAsync(new QBEntityCallback<Integer>() {
    @Override
    public void onSuccess(Integer totalCount, Bundle bundle) {

    }

    @Override
    public void onError(QBResponseException e) {

    }
});
val dialogsIds = HashSet<String>()
dialogsIds.add("44g9867978v894365tf7g3y4")
dialogsIds.add("47r8738478394ffdi39id493")
  
QBRestChatService.getTotalUnreadMessagesCount(dialogsIds, null).performAsync(object : QBEntityCallback<Int> {
    override fun onSuccess(integer: Int?, bundle: Bundle?) {

    }

    override fun onError(e: QBResponseException?) {

    }
})

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.

Updated 4 days ago


What's Next

Messaging

Dialogs


Learn how to create and manage dialogs.

Suggested Edits are limited on API Reference Pages

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