Dialogs

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.

Visit Key Concepts page to learn 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 ID of the opponent you want to create a chat with.

Dart

List<int> occupantsIds = [89987878, 98987887];
String dialogName = "someone chat";
int dialogType = QBChatDialogTypes.CHAT;

try {
  QBDialog? createdDialog = await QB.chat.createDialog(occupantsIds, dialogName, dialogType: dialogType);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

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

Dart

List<int> occupantIds = [234234324, 3243243];
String dialogName = "Group Chat";
String dialogPhoto = "some photo url";
int dialogType = QBChatDialogTypes.GROUP_CHAT;

try {
  QBDialog? createdDialog = await QB.chat.createDialog(occupantIds, dialogName, dialogType: dialogType, dialogPhoto: dialogPhoto);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

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.

Dart

List<int> occupantIds = [234234324, 3243243];
int dialogType = QBChatDialogTypes.PUBLIC_CHAT;
String dialogName = "Public Chat";

try {
  QBDialog? createdDialog = await QB.chat.createDialog(occupantIds, dialogName, dialogType: dialogType);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

The createDialog() method accepts the following arguments:

Argument	Required	Description
occupantIds	yes	A list of opponents IDs.- If the occupantsIds array is empty and type is not provided, the public dialog is created.- If the occupantsIds has a single user and type is not provided, the private dialog is created.- If the occupantsIds has more then one userId and type is not provided, a group dialog is created.
dialogName	yes	The name of the dialog. Required only for group and public dialog types. Not needed for private dialog.
dialogType	no	A type of the dialog. Possible values: `QBChatDialogTypes.CHAT`, `QBChatDialogTypes.GROUP\_CHAT` or `QBChatDialogTypes.PUBLIC\_CHAT`. By default, the public dialog is created.
dialogPhoto	no	A url of the image. Can be a link to a file in Content module, Custom Objects module or just a web link.Must be a String.
isJoinRequired	no	Defines whether participants must join before sending or receiving real-time messages. Applies only to group dialogs.

Create group dialog with join required

Available since QuickBlox Flutter SDK v0.19.0.Prior to server version 2.34.0, all group dialogs required joining. Starting from server version 2.34.0, new applications do not require joining, while existing applications retain the previous behavior. You can change the default in application settings.If isJoinRequired is explicitly set when creating a dialog, the provided value takes priority over the default in application settings.Most applications do not need this feature. The default behavior where participants can send and receive real-time messages without joining is recommended for most use cases.

When creating a group dialog, you can set the isJoinRequired parameter to true to require participants to explicitly join the dialog before they can send or receive real-time messages. This is only needed when you want to restrict real-time messaging in specific dialogs until participants explicitly join. By default, isJoinRequired is false and participants can message without joining. This parameter applies only to group dialogs. You can change the default in application settings.

Dart

List<int> occupantIds = [234234324, 3243243];
String dialogName = "Group Chat";
int dialogType = QBChatDialogTypes.GROUP_CHAT;

try {
  QBDialog? createdDialog = await QB.chat.createDialog(
    dialogType,
    occupantsIds: occupantIds,
    dialogName: dialogName,
    isJoinRequired: true,
  );

  bool isJoinRequired = await QB.chat.isJoinRequired(createdDialog!.id!);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Check if join required for group dialog

The isJoinRequired() method is available starting from QuickBlox Flutter SDK v0.19.0. See Create group dialog with join required for details.

You can get the isJoinRequired value for any group dialog:

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  bool isJoinRequired = await QB.chat.isJoinRequired(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Join group dialog

Starting from QuickBlox Flutter SDK v0.19.0, joining a group dialog is required only when isJoinRequired is set to true for a dialog. See Create group dialog with join required for details.

If isJoinRequired is set to true for a group dialog, you need to join it by calling the joinDialog() method before you can send or receive real-time messages. See this section to learn how to send/receive real-time messages. You must join the dialog after every new connection or reconnection. If the connection is lost and then restored, whether manually or automatically, you need to call joinDialog() again for each dialog where isJoinRequired is true.

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  await QB.chat.joinDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

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 another user. See this section to learn how to add occupants to the group dialog.

To check if you have already joined the dialog, call the isJoinedDialog() method:

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  bool isJoinedDialog = await QB.chat.isJoinedDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Join public dialog

Before you start chatting in a public dialog, you must join it by calling the joinDialog() method. Unlike group dialogs, joining a public dialog is always required. If you’ve successfully joined the dialog, you can send/receive real-time messages. See this section to learn how to send/receive real-time messages. You must join the dialog after every new connection or reconnection. If the connection is lost and then restored, whether manually or automatically, you need to call joinDialog() again.

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  await QB.chat.joinDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

To check if you have already joined the dialog, call the isJoinedDialog() method:

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  bool isJoinedDialog = await QB.chat.isJoinedDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Leave group dialog

You can leave the group dialog by calling the leaveDialog() method. After leaving, you will stop receiving real-time messages from this dialog. You need to join the dialog again to resume receiving real-time messages.

Starting from QuickBlox Flutter SDK v0.19.0, leaving a group dialog is only needed when isJoinRequired is set to true. If isJoinRequired is false, you do not need to call leaveDialog().

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  await QB.chat.leaveDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

When you leave a group dialog, your user ID is still present in the occupantIDs array in the dialog model. The dialog will still appear in the list of dialogs and you will still have access to the chat history.To remove yourself from the group dialog, use the updateDialog() method. See this section to learn how to remove occupants from the group dialog.

Leave public dialog

You can leave the public dialog by calling the leaveDialog() method. After leaving, you will stop receiving real-time messages from this dialog. You need to join the dialog again to resume receiving real-time messages.

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  await QB.chat.leaveDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

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 containing test value in their names, sorted in ascending order by the QBChatDialogFilterFields.LAST_MESSAGE_DATE_SENT field, and limited to 100 dialogs on the page with 25 dialogs skipped at the beginning.

Dart

QBSort sort = QBSort();
sort.field = QBChatDialogSorts.LAST_MESSAGE_DATE_SENT;
sort.ascending = true;

QBFilter filter = QBFilter();
filter.field = QBChatDialogFilterFields.NAME;
filter.operator = QBChatDialogFilterOperators.CTN;
filter.value = "test value";

int limit = 100;
int skip = 25;

try {
  List<QBDialog?> dialogs = await QB.chat.getDialogs(sort: sort, filter: filter, limit: limit, skip: skip);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Argument	Required	Description
sort	no	Specifies sorting criteria for the field.
filter	no	Specifies filtering criteria for the field.
limit	no	Limit search results to N records. Useful for pagination. Default value: 100.
skip	no	Skip N records in search results. Useful for pagination. Default (if not specified): 0.

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

Search operators

You can use search operators to get more specific search results. The request below will return all dialogs containing the flutter_chat in their names.

Dart

try {
  QBFilter filter = QBFilter();
  filter.field = QBChatDialogFilterFields.NAME;
  filter.operator = QBChatDialogFilterOperators.CTN;
  filter.value = "flutter_chat";

  List<QBDialog?> dialogs = await QB.chat.getDialogs(filter: filter);
} on PlatformException catch (e) {
	// some error occurred, look at the exception message for more details
}

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

Search operators	Applicable to types	Applicable to fields	Description
lt	number, string, date	last_message_date_sent, created_at, updated_at	Less Than operator.
lte	number, string, date	last_message_date_sent, created_at, updated_at	Less Than or Equal to operator.
gt	number, string, date	last_message_date_sent, created_at, updated_at	Greater Than operator.
gte	number, string, date	last_message_date_sent, created_at, updated_at	Greater Than or Equal to operator.
ne	number, string, date	_id, name, last_message_date_sent	Not Equal to operator.
in	number, string, date	type, last_message_date_sent, name	IN array operator.
nin	number, string, date	last_message_date_sent	IN array operator.
all	number	occupants_ids	ALL are contained in array.
ctn	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 a list of dialogs sorted by the QBChatDialogSorts.LAST_MESSAGE_DATE_SENT field in descending order.

Dart

try {
  QBSort sort = QBSort();
  sort.field = QBChatDialogSorts.LAST_MESSAGE_DATE_SENT;
  sort.ascending = false;

  List<QBDialog?> dialogs = await QB.chat.getDialogs(sort: sort);
} on PlatformException catch (e) {
	// some error occurred, look at the exception message for more details
}

Here are the sort options that you can use to order the search results.

Sort options	Applicable to types	Applicable to fields	Description
ascending	All types	id, created_at, name, last_message_date_sent	Sort results in ascending order by setting the ascending as true.
descending	All types	id, created_at, name, last_message_date_sent	Sort results in descending order by setting the ascending as false.

Update dialog

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

Dart

String dialogId = "adfpo443ldfJLsdjdsf324lkjer";
String dialogName = "Some Chat";
String dialogPhoto = "some photo url";

try {
  QBDialog? updatedDialog = await QB.chat.updateDialog(dialogId, dialogName: dialogName, dialogPhoto: dialogPhoto);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Argument	Required	Description
dialogId	yes	The ID of the dialog.
dialogName	no	A name of the dialog.
dialogPhoto	no	A url of the image. Should be a String.

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 occupants

Set the addUsers argument to add occupants to the dialog. As a result, the ID of the opponent will be added to the occupantIds array.

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";
List<int> addUsers = [234234111, 32432777];

try {
  QBDialog? updatedDialog = await QB.chat.updateDialog(dialogId, addUsers: addUsers);
} on PlatformException catch (e) {
  // some error occurred, 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,Occupant	✗

Remove occupants

Set the removeUsers argument to remove occupants from the dialog. As a result, the ID of the opponent will be removed from the occupantIds array.

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";
List<int> removeUsers = [234234888, 3243999];

try {
  QBDialog? updatedDialog = await QB.chat.updateDialog(dialogId, removeUsers: removeUsers);
} on PlatformException catch (e) {
  // some error occurred, look at the exception message for more details
}

Capabilities	Public dialog	Group dialog	Private dialog
Remove other users	✗	Owner	✗
Remove yourself	✗	Owner,Occupant	✗

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 occupantIds 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 Leave group dialog and Leave public dialog for more information.

Dart

String dialogId = "fdb5f5a28388a64aba5b2f57570b13f827012bba";

try {
  await QB.chat.deleteDialog(dialogId);
} on PlatformException catch (e) {
  // some error occurred, 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

Resources

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

SDKs

iOS

Android

JavaScript

React Native

Flutter

Before you begin

Dialog types

Create dialog

Create group dialog with join required

Check if join required for group dialog

Join group dialog

Join public dialog

Leave group dialog

Leave public dialog

Retrieve list of dialogs

Search operators

Sort operators

Update dialog

Add occupants

Remove occupants

Delete dialog

Resources

​Before you begin

​Dialog types

​Create dialog

​Create group dialog with join required

​Check if join required for group dialog

​Join group dialog

​Join public dialog

​Leave group dialog

​Leave public dialog

​Retrieve list of dialogs

​Search operators

​Sort operators

​Update dialog

​Add occupants

​Remove occupants

​Delete dialog

​Resources

Before you begin

Dialog types

Create dialog

Create group dialog with join required

Check if join required for group dialog

Join group dialog

Join public dialog

Leave group dialog

Leave public dialog

Retrieve list of dialogs

Search operators

Sort operators

Update dialog

Add occupants

Remove occupants

Delete dialog

Resources